diff options
author | Martin Liska <mliska@suse.cz> | 2022-11-07 12:54:13 +0100 |
---|---|---|
committer | Martin Liska <mliska@suse.cz> | 2022-11-09 09:00:35 +0100 |
commit | c63539ffe4c0e327337a1a51f638d9c8c958cb26 (patch) | |
tree | b7e150794087c7f95700d86df3075e27c37c1f77 /gcc/fortran | |
parent | 38ec5e4bc8fed58e278e6dcad999d38c5efc1340 (diff) | |
download | gcc-c63539ffe4c0e327337a1a51f638d9c8c958cb26.zip gcc-c63539ffe4c0e327337a1a51f638d9c8c958cb26.tar.gz gcc-c63539ffe4c0e327337a1a51f638d9c8c958cb26.tar.bz2 |
sphinx: copy files from texi2rst-generated repository
ChangeLog:
* doc/Makefile: New file.
* doc/_static/custom.css: New file.
* doc/baseconf.py: New file.
* doc/bsd.rst: New file.
* doc/contrib.rst: New file.
* doc/contribute.rst: New file.
* doc/cppdiropts.rst: New file.
* doc/cppenv.rst: New file.
* doc/cppopts.rst: New file.
* doc/cppwarnopts.rst: New file.
* doc/favicon.ico: New file.
* doc/funding.rst: New file.
* doc/gcc_sphinx.py: New file.
* doc/gnu.rst: New file.
* doc/gnu_free_documentation_license.rst: New file.
* doc/gpl-3.0.rst: New file.
* doc/indices-and-tables.rst: New file.
* doc/lgpl-2.1.rst: New file.
* doc/logo.pdf: New file.
* doc/logo.svg: New file.
* doc/md.rst: New file.
* doc/requirements.txt: New file.
gcc/d/ChangeLog:
* doc/conf.py: New file.
* doc/copyright.rst: New file.
* doc/general-public-license-3.rst: New file.
* doc/gnu-free-documentation-license.rst: New file.
* doc/index.rst: New file.
* doc/indices-and-tables.rst: New file.
* doc/invoking-gdc.rst: New file.
* doc/invoking-gdc/code-generation.rst: New file.
* doc/invoking-gdc/developer-options.rst: New file.
* doc/invoking-gdc/input-and-output-files.rst: New file.
* doc/invoking-gdc/options-for-directory-search.rst: New file.
* doc/invoking-gdc/options-for-linking.rst: New file.
* doc/invoking-gdc/runtime-options.rst: New file.
* doc/invoking-gdc/warnings.rst: New file.
gcc/ChangeLog:
* doc/cpp/character-sets.rst: New file.
* doc/cpp/conditional-syntax.rst: New file.
* doc/cpp/conditional-uses.rst: New file.
* doc/cpp/conditionals.rst: New file.
* doc/cpp/conf.py: New file.
* doc/cpp/copyright.rst: New file.
* doc/cpp/deleted-code.rst: New file.
* doc/cpp/diagnostics.rst: New file.
* doc/cpp/environment-variables.rst: New file.
* doc/cpp/gnu-free-documentation-license.rst: New file.
* doc/cpp/header-files.rst: New file.
* doc/cpp/header-files/alternatives-to-wrapper-ifndef.rst: New file.
* doc/cpp/header-files/computed-includes.rst: New file.
* doc/cpp/header-files/include-operation.rst: New file.
* doc/cpp/header-files/include-syntax.rst: New file.
* doc/cpp/header-files/once-only-headers.rst: New file.
* doc/cpp/header-files/search-path.rst: New file.
* doc/cpp/header-files/system-headers.rst: New file.
* doc/cpp/header-files/wrapper-headers.rst: New file.
* doc/cpp/implementation-defined-behavior.rst: New file.
* doc/cpp/implementation-details.rst: New file.
* doc/cpp/implementation-limits.rst: New file.
* doc/cpp/index.rst: New file.
* doc/cpp/indices-and-tables.rst: New file.
* doc/cpp/initial-processing.rst: New file.
* doc/cpp/invocation.rst: New file.
* doc/cpp/line-control.rst: New file.
* doc/cpp/macros.rst: New file.
* doc/cpp/macros/concatenation.rst: New file.
* doc/cpp/macros/directives-within-macro-arguments.rst: New file.
* doc/cpp/macros/function-like-macros.rst: New file.
* doc/cpp/macros/macro-arguments.rst: New file.
* doc/cpp/macros/macro-pitfalls.rst: New file.
* doc/cpp/macros/object-like-macros.rst: New file.
* doc/cpp/macros/predefined-macros.rst: New file.
* doc/cpp/macros/stringizing.rst: New file.
* doc/cpp/macros/undefining-and-redefining-macros.rst: New file.
* doc/cpp/macros/variadic-macros.rst: New file.
* doc/cpp/obsolete-features.rst: New file.
* doc/cpp/other-directives.rst: New file.
* doc/cpp/overview.rst: New file.
* doc/cpp/pragmas.rst: New file.
* doc/cpp/preprocessor-output.rst: New file.
* doc/cpp/the-preprocessing-language.rst: New file.
* doc/cpp/tokenization.rst: New file.
* doc/cpp/traditional-lexical-analysis.rst: New file.
* doc/cpp/traditional-macros.rst: New file.
* doc/cpp/traditional-miscellany.rst: New file.
* doc/cpp/traditional-mode.rst: New file.
* doc/cpp/traditional-warnings.rst: New file.
* doc/cppinternals/conf.py: New file.
* doc/cppinternals/copyright.rst: New file.
* doc/cppinternals/cppinternals.rst: New file.
* doc/cppinternals/cpplib.rst: New file.
* doc/cppinternals/files.rst: New file.
* doc/cppinternals/index.rst: New file.
* doc/cppinternals/indices-and-tables.rst: New file.
* doc/cppinternals/internal-representation-of-macros.rst: New file.
* doc/cppinternals/just-which-line-number-anyway.rst: New file.
* doc/cppinternals/lexing-a-line.rst: New file.
* doc/cppinternals/lexing-a-token.rst: New file.
* doc/cppinternals/looking-for-a-function-like-macros-opening-parenthesis.rst: New file.
* doc/cppinternals/macro-expansion-overview.rst: New file.
* doc/cppinternals/marking-tokens-ineligible-for-future-expansion.rst: New file.
* doc/cppinternals/multiple-include-optimization.rst: New file.
* doc/cppinternals/overview.rst: New file.
* doc/cppinternals/representation-of-line-numbers.rst: New file.
* doc/cppinternals/scanning-the-replacement-list-for-macros-to-expand.rst: New file.
* doc/gcc/binary-compatibility.rst: New file.
* doc/gcc/c++-implementation-defined-behavior.rst: New file.
* doc/gcc/c-implementation-defined-behavior.rst: New file.
* doc/gcc/c-implementation-defined-behavior/architecture.rst: New file.
* doc/gcc/c-implementation-defined-behavior/arrays-and-pointers.rst: New file.
* doc/gcc/c-implementation-defined-behavior/characters.rst: New file.
* doc/gcc/c-implementation-defined-behavior/declarators.rst: New file.
* doc/gcc/c-implementation-defined-behavior/environment.rst: New file.
* doc/gcc/c-implementation-defined-behavior/floating-point.rst: New file.
* doc/gcc/c-implementation-defined-behavior/hints.rst: New file.
* doc/gcc/c-implementation-defined-behavior/identifiers.rst: New file.
* doc/gcc/c-implementation-defined-behavior/integers.rst: New file.
* doc/gcc/c-implementation-defined-behavior/library-functions.rst: New file.
* doc/gcc/c-implementation-defined-behavior/locale-specific-behavior.rst: New file.
* doc/gcc/c-implementation-defined-behavior/preprocessing-directives.rst: New file.
* doc/gcc/c-implementation-defined-behavior/qualifiers.rst: New file.
* doc/gcc/c-implementation-defined-behavior/statements.rst: New file.
* doc/gcc/c-implementation-defined-behavior/structures-unions-enumerations-and-bit-fields.rst:
New file.
* doc/gcc/c-implementation-defined-behavior/translation.rst: New file.
* doc/gcc/conditionally-supported-behavior.rst: New file.
* doc/gcc/conf.py: New file.
* doc/gcc/contributing-to-gcc-development.rst: New file.
* doc/gcc/contributors-to-gcc.rst: New file.
* doc/gcc/copyright.rst: New file.
* doc/gcc/exception-handling.rst: New file.
* doc/gcc/extensions-to-the-c++-language.rst: New file.
* doc/gcc/extensions-to-the-c++-language/backwards-compatibility.rst: New file.
* doc/gcc/extensions-to-the-c++-language/c++-concepts.rst: New file.
* doc/gcc/extensions-to-the-c++-language/c++-interface-and-implementation-pragmas.rst:
New file.
* doc/gcc/extensions-to-the-c++-language/c++-specific-variable-function-and-type-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c++-language/deprecated-features.rst: New file.
* doc/gcc/extensions-to-the-c++-language/extracting-the-function-pointer-from-a-bound-pointer-to-member-function.rst:
New file.
* doc/gcc/extensions-to-the-c++-language/function-multiversioning.rst: New file.
* doc/gcc/extensions-to-the-c++-language/restricting-pointer-aliasing.rst: New file.
* doc/gcc/extensions-to-the-c++-language/type-traits.rst: New file.
* doc/gcc/extensions-to-the-c++-language/vague-linkage.rst: New file.
* doc/gcc/extensions-to-the-c++-language/when-is-a-volatile-c++-object-accessed.rst:
New file.
* doc/gcc/extensions-to-the-c++-language/wheres-the-template.rst: New file.
* doc/gcc/extensions-to-the-c-language-family.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/128-bit-integers.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/additional-floating-types.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/alternate-keywords.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/an-inline-function-is-as-fast-as-a-macro.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/arithmetic-on-void-and-function-pointers.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/arrays-of-length-zero.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/arrays-of-variable-length.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/attribute-syntax.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/binary-constants-using-the-0b-prefix.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/built-in-functions-for-memory-model-aware-atomic-operations.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/built-in-functions-to-perform-arithmetic-with-overflow-checking.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/c++-style-comments.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/case-ranges.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/cast-to-a-union-type.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/complex-numbers.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/compound-literals.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/conditionals-with-omitted-operands.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/constructing-function-calls.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/decimal-floating-types.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/aarch64-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/amd-gcn-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/arc-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/arm-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/avr-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/blackfin-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/bpf-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/c-sky-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/common-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/epiphany-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/h8-300-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/ia-64-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/m32c-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/m32r-d-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/m68k-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/mcore-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/mep-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/microblaze-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/microsoft-windows-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/mips-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/msp430-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/nds32-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/nios-ii-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/nvidia-ptx-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/powerpc-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/risc-v-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/rl78-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/rx-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/s-390-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/sh-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/symbian-os-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/v850-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/visium-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/x86-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/xstormy16-function-attributes.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/designated-initializers.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/determining-the-alignment-of-functions-types-or-variables.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/dollar-signs-in-identifier-names.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/double-word-integers.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/enumerator-attributes.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/fixed-point-types.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/format-checks-specific-to-particular-target-machines.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/function-names-as-strings.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/getting-the-return-or-frame-address-of-a-function.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/half-precision-floating-point.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/hex-floats.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/how-to-use-inline-assembly-language-in-c-code.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/incomplete-enum-types.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/label-attributes.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/labels-as-values.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/legacy-sync-built-in-functions-for-atomic-memory-access.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/locally-declared-labels.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/macros-with-a-variable-number-of-arguments.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/mixed-declarations-labels-and-code.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/named-address-spaces.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/nested-functions.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/non-constant-initializers.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/non-lvalue-arrays-may-have-subscripts.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/nonlocal-gotos.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/object-size-checking-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/other-built-in-functions-provided-by-gcc.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/pointer-arguments-in-variadic-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/pointers-to-arrays-with-qualifiers-work-as-expected.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/pragmas-accepted-by-gcc.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/prototypes-and-old-style-function-definitions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/referring-to-a-type-with-typeof.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/slightly-looser-rules-for-escaped-newlines.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/specifying-attributes-of-types.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/specifying-attributes-of-variables.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/statement-attributes.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/statements-and-declarations-in-expressions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/structures-with-no-members.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/support-for-offsetof.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/aarch64-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/alpha-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/altera-nios-ii-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/arc-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/arc-simd-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-armv8-m-security-extensions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-c-language-extensions-acle.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-floating-point-status-and-control-intrinsics.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-iwmmxt-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/avr-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/basic-powerpc-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/blackfin-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/bpf-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/fr-v-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-dsp-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-loongson-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-paired-single-support.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-simd-architecture-msa-support.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/msp430-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/nds32-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/other-mips-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/picochip-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-altivec-vsx-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-atomic-memory-operation-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-hardware-transactional-memory-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-matrix-multiply-assist-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/pru-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/risc-v-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/rx-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/s-390-system-z-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/sh-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/sparc-vis-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/ti-c6x-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/x86-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/x86-control-flow-protection-intrinsics.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/target-builtins/x86-transactional-memory-intrinsics.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/the-character-esc-in-constants.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/thread-local-storage.rst: New file.
* doc/gcc/extensions-to-the-c-language-family/unnamed-structure-and-union-fields.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/using-vector-instructions-through-built-in-functions.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/when-is-a-volatile-object-accessed.rst:
New file.
* doc/gcc/extensions-to-the-c-language-family/x86-specific-memory-model-extensions-for-transactional-memory.rst:
New file.
* doc/gcc/funding.rst: New file.
* doc/gcc/gcc-command-options.rst: New file.
* doc/gcc/gcc-command-options/c++-modules.rst: New file.
* doc/gcc/gcc-command-options/compiling-c++-programs.rst: New file.
* doc/gcc/gcc-command-options/description.rst: New file.
* doc/gcc/gcc-command-options/environment-variables-affecting-gcc.rst: New file.
* doc/gcc/gcc-command-options/gcc-developer-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/aarch64-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/adapteva-epiphany-options.rst:
New file.
* doc/gcc/gcc-command-options/machine-dependent-options/amd-gcn-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/arc-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/arm-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/avr-mmcu.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/avr-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/blackfin-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/c-sky-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/c6x-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/cris-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/darwin-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/dec-alpha-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/ebpf-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/fr30-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/frv-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/ft32-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/gnu-linux-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/h8-300-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/hppa-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/ia-64-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/ibm-rs-6000-and-powerpc-options.rst:
New file.
* doc/gcc/gcc-command-options/machine-dependent-options/lm32-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/loongarch-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/m32c-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/m32r-d-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/m680x0-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/mcore-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/mep-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/microblaze-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/mips-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/mmix-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/mn10300-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/moxie-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/msp430-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/nds32-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/nios-ii-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/nvidia-ptx-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/openrisc-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/options-for-system-v.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/pdp-11-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/picochip-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/powerpc-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/pru-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/risc-v-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/rl78-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/rx-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/s-390-and-zseries-options.rst:
New file.
* doc/gcc/gcc-command-options/machine-dependent-options/score-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/sh-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/solaris-2-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/sparc-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/v850-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/vax-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/visium-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/vms-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/vxworks-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/x86-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/x86-windows-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/xstormy16-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/xtensa-options.rst: New file.
* doc/gcc/gcc-command-options/machine-dependent-options/zseries-options.rst: New file.
* doc/gcc/gcc-command-options/option-summary.rst: New file.
* doc/gcc/gcc-command-options/options-controlling-c++-dialect.rst: New file.
* doc/gcc/gcc-command-options/options-controlling-c-dialect.rst: New file.
* doc/gcc/gcc-command-options/options-controlling-objective-c-and-objective-c++-dialects.rst:
New file.
* doc/gcc/gcc-command-options/options-controlling-the-kind-of-output.rst: New file.
* doc/gcc/gcc-command-options/options-controlling-the-preprocessor.rst: New file.
* doc/gcc/gcc-command-options/options-for-code-generation-conventions.rst: New file.
* doc/gcc/gcc-command-options/options-for-debugging-your-program.rst: New file.
* doc/gcc/gcc-command-options/options-for-directory-search.rst: New file.
* doc/gcc/gcc-command-options/options-for-linking.rst: New file.
* doc/gcc/gcc-command-options/options-that-control-optimization.rst: New file.
* doc/gcc/gcc-command-options/options-that-control-static-analysis.rst: New file.
* doc/gcc/gcc-command-options/options-to-control-diagnostic-messages-formatting.rst:
New file.
* doc/gcc/gcc-command-options/options-to-request-or-suppress-warnings.rst: New file.
* doc/gcc/gcc-command-options/passing-options-to-the-assembler.rst: New file.
* doc/gcc/gcc-command-options/program-instrumentation-options.rst: New file.
* doc/gcc/gcc-command-options/specifying-subprocesses-and-the-switches-to-pass-to-them.rst:
New file.
* doc/gcc/gcc-command-options/using-precompiled-headers.rst: New file.
* doc/gcc/gcc.rst: New file.
* doc/gcc/gcov-dump.rst: New file.
* doc/gcc/gcov-tool.rst: New file.
* doc/gcc/gcov.rst: New file.
* doc/gcc/gcov/brief-description-of-gcov-data-files.rst: New file.
* doc/gcc/gcov/data-file-relocation-to-support-cross-profiling.rst: New file.
* doc/gcc/gcov/introduction-to-gcov.rst: New file.
* doc/gcc/gcov/invoking-gcov.rst: New file.
* doc/gcc/gcov/profiling-and-test-coverage-in-freestanding-environments.rst: New file.
* doc/gcc/gcov/using-gcov-with-gcc-optimization.rst: New file.
* doc/gcc/general-public-license-3.rst: New file.
* doc/gcc/gnu-free-documentation-license.rst: New file.
* doc/gcc/gnu-objective-c-features.rst: New file.
* doc/gcc/gnu-objective-c-features/compatibilityalias.rst: New file.
* doc/gcc/gnu-objective-c-features/constant-string-objects.rst: New file.
* doc/gcc/gnu-objective-c-features/exceptions.rst: New file.
* doc/gcc/gnu-objective-c-features/fast-enumeration.rst: New file.
* doc/gcc/gnu-objective-c-features/garbage-collection.rst: New file.
* doc/gcc/gnu-objective-c-features/gnu-objective-c-runtime-api.rst: New file.
* doc/gcc/gnu-objective-c-features/load-executing-code-before-main.rst: New file.
* doc/gcc/gnu-objective-c-features/messaging-with-the-gnu-objective-c-runtime.rst: New file.
* doc/gcc/gnu-objective-c-features/synchronization.rst: New file.
* doc/gcc/gnu-objective-c-features/type-encoding.rst: New file.
* doc/gcc/gnu.rst: New file.
* doc/gcc/have-you-found-a-bug.rst: New file.
* doc/gcc/how-and-where-to-report-bugs.rst: New file.
* doc/gcc/how-to-get-help-with-gcc.rst: New file.
* doc/gcc/index.rst: New file.
* doc/gcc/indices-and-tables.rst: New file.
* doc/gcc/known-causes-of-trouble-with-gcc.rst: New file.
* doc/gcc/known-causes-of-trouble-with-gcc/actual-bugs-we-havent-fixed-yet.rst: New file.
* doc/gcc/known-causes-of-trouble-with-gcc/certain-changes-we-dont-want-to-make.rst:
New file.
* doc/gcc/known-causes-of-trouble-with-gcc/common-misunderstandings-with-gnu-c.rst:
New file.
* doc/gcc/known-causes-of-trouble-with-gcc/disappointments-and-misunderstandings.rst:
New file.
* doc/gcc/known-causes-of-trouble-with-gcc/fixed-header-files.rst: New file.
* doc/gcc/known-causes-of-trouble-with-gcc/incompatibilities-of-gcc.rst: New file.
* doc/gcc/known-causes-of-trouble-with-gcc/interoperation.rst: New file.
* doc/gcc/known-causes-of-trouble-with-gcc/standard-libraries.rst: New file.
* doc/gcc/known-causes-of-trouble-with-gcc/warning-messages-and-error-messages.rst:
New file.
* doc/gcc/language-standards-supported-by-gcc.rst: New file.
* doc/gcc/language-standards-supported-by-gcc/c++-language.rst: New file.
* doc/gcc/language-standards-supported-by-gcc/c-language.rst: New file.
* doc/gcc/language-standards-supported-by-gcc/d-language.rst: New file.
* doc/gcc/language-standards-supported-by-gcc/go-language.rst: New file.
* doc/gcc/language-standards-supported-by-gcc/objective-c-and-objective-c++-languages.rst:
New file.
* doc/gcc/language-standards-supported-by-gcc/references-for-other-languages.rst: New file.
* doc/gcc/lto-dump.rst: New file.
* doc/gcc/programming-languages-supported-by-gcc.rst: New file.
* doc/gcc/reporting-bugs.rst: New file.
* doc/gccint/analysis-and-optimization-of-gimple-tuples.rst: New file.
* doc/gccint/analysis-and-optimization-of-gimple-tuples/alias-analysis.rst: New file.
* doc/gccint/analysis-and-optimization-of-gimple-tuples/annotations.rst: New file.
* doc/gccint/analysis-and-optimization-of-gimple-tuples/memory-model.rst: New file.
* doc/gccint/analysis-and-optimization-of-gimple-tuples/ssa-operands.rst: New file.
* doc/gccint/analysis-and-optimization-of-gimple-tuples/static-single-assignment.rst:
New file.
* doc/gccint/analysis-and-representation-of-loops.rst: New file.
* doc/gccint/analysis-and-representation-of-loops/data-dependency-analysis.rst: New file.
* doc/gccint/analysis-and-representation-of-loops/iv-analysis-on-rtl.rst: New file.
* doc/gccint/analysis-and-representation-of-loops/loop-closed-ssa-form.rst: New file.
* doc/gccint/analysis-and-representation-of-loops/loop-manipulation.rst: New file.
* doc/gccint/analysis-and-representation-of-loops/loop-querying.rst: New file.
* doc/gccint/analysis-and-representation-of-loops/loop-representation.rst: New file.
* doc/gccint/analysis-and-representation-of-loops/number-of-iterations-analysis.rst:
New file.
* doc/gccint/analysis-and-representation-of-loops/scalar-evolutions.rst: New file.
* doc/gccint/analyzer-internals.rst: New file.
* doc/gccint/collect2.rst: New file.
* doc/gccint/conf.py: New file.
* doc/gccint/contributing-to-gcc-development.rst: New file.
* doc/gccint/contributors-to-gcc.rst: New file.
* doc/gccint/control-flow-graph.rst: New file.
* doc/gccint/control-flow-graph/basic-blocks.rst: New file.
* doc/gccint/control-flow-graph/edges.rst: New file.
* doc/gccint/control-flow-graph/liveness-information.rst: New file.
* doc/gccint/control-flow-graph/maintaining-the-cfg.rst: New file.
* doc/gccint/control-flow-graph/profile-information.rst: New file.
* doc/gccint/copyright.rst: New file.
* doc/gccint/debugging-the-analyzer.rst: New file.
* doc/gccint/funding.rst: New file.
* doc/gccint/gcc-and-portability.rst: New file.
* doc/gccint/general-public-license-3.rst: New file.
* doc/gccint/generic.rst: New file.
* doc/gccint/generic/attributes-in-trees.rst: New file.
* doc/gccint/generic/c-and-c++-trees.rst: New file.
* doc/gccint/generic/declarations.rst: New file.
* doc/gccint/generic/deficiencies.rst: New file.
* doc/gccint/generic/expressions.rst: New file.
* doc/gccint/generic/functions.rst: New file.
* doc/gccint/generic/language-dependent-trees.rst: New file.
* doc/gccint/generic/overview.rst: New file.
* doc/gccint/generic/statements.rst: New file.
* doc/gccint/generic/types.rst: New file.
* doc/gccint/gimple-api.rst: New file.
* doc/gccint/gimple.rst: New file.
* doc/gccint/gimple/adding-a-new-gimple-statement-code.rst: New file.
* doc/gccint/gimple/class-hierarchy-of-gimple-statements.rst: New file.
* doc/gccint/gimple/exception-handling.rst: New file.
* doc/gccint/gimple/gimple-instruction-set.rst: New file.
* doc/gccint/gimple/gimple-sequences.rst: New file.
* doc/gccint/gimple/manipulating-gimple-statements.rst: New file.
* doc/gccint/gimple/operands.rst: New file.
* doc/gccint/gimple/sequence-iterators.rst: New file.
* doc/gccint/gimple/statement-and-operand-traversals.rst: New file.
* doc/gccint/gimple/temporaries.rst: New file.
* doc/gccint/gimple/tuple-representation.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleasm.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleassign.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimplebind.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimplecall.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimplecatch.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimplecond.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpledebug.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleehfilter.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimplegoto.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimplelabel.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimplenop.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompatomicload.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompatomicstore.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompcontinue.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompcritical.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompfor.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompmaster.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompordered.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompparallel.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompreturn.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompsection.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompsections.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleompsingle.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimplephi.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleresx.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimplereturn.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpleswitch.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimpletry.rst: New file.
* doc/gccint/gimple/tuple-specific-accessors/gimplewithcleanupexpr.rst: New file.
* doc/gccint/gnu-free-documentation-license.rst: New file.
* doc/gccint/guidelines-for-diagnostics.rst: New file.
* doc/gccint/guidelines-for-options.rst: New file.
* doc/gccint/host-common.rst: New file.
* doc/gccint/host-configuration.rst: New file.
* doc/gccint/host-filesystem.rst: New file.
* doc/gccint/host-makefile-fragments.rst: New file.
* doc/gccint/host-misc.rst: New file.
* doc/gccint/index.rst: New file.
* doc/gccint/indices-and-tables.rst: New file.
* doc/gccint/interfacing-to-gcc-output.rst: New file.
* doc/gccint/introduction.rst: New file.
* doc/gccint/language-front-ends-in-gcc.rst: New file.
* doc/gccint/link-time-optimization.rst: New file.
* doc/gccint/link-time-optimization/design-overview.rst: New file.
* doc/gccint/link-time-optimization/internal-flags-controlling-lto1.rst: New file.
* doc/gccint/link-time-optimization/lto-file-sections.rst: New file.
* doc/gccint/link-time-optimization/using-summary-information-in-ipa-passes.rst: New file.
* doc/gccint/link-time-optimization/whole-program-assumptions-linker-plugin-and-symbol-visibilities.rst:
New file.
* doc/gccint/machine-descriptions.rst: New file.
* doc/gccint/machine-descriptions/c-statements-for-assembler-output.rst: New file.
* doc/gccint/machine-descriptions/canonicalization-of-instructions.rst: New file.
* doc/gccint/machine-descriptions/conditional-execution.rst: New file.
* doc/gccint/machine-descriptions/constant-definitions.rst: New file.
* doc/gccint/machine-descriptions/defining-how-to-split-instructions.rst: New file.
* doc/gccint/machine-descriptions/defining-jump-instruction-patterns.rst: New file.
* doc/gccint/machine-descriptions/defining-looping-instruction-patterns.rst: New file.
* doc/gccint/machine-descriptions/defining-rtl-sequences-for-code-generation.rst: New file.
* doc/gccint/machine-descriptions/everything-about-instruction-patterns.rst: New file.
* doc/gccint/machine-descriptions/example-of-defineinsn.rst: New file.
* doc/gccint/machine-descriptions/including-patterns-in-machine-descriptions.rst: New file.
* doc/gccint/machine-descriptions/instruction-attributes.rst: New file.
* doc/gccint/machine-descriptions/interdependence-of-patterns.rst: New file.
* doc/gccint/machine-descriptions/iterators.rst: New file.
* doc/gccint/machine-descriptions/machine-specific-peephole-optimizers.rst: New file.
* doc/gccint/machine-descriptions/operand-constraints.rst: New file.
* doc/gccint/machine-descriptions/output-templates-and-operand-substitution.rst: New file.
* doc/gccint/machine-descriptions/overview-of-how-the-machine-description-is-used.rst:
New file.
* doc/gccint/machine-descriptions/predicates.rst: New file.
* doc/gccint/machine-descriptions/rtl-template.rst: New file.
* doc/gccint/machine-descriptions/rtl-templates-transformations.rst: New file.
* doc/gccint/machine-descriptions/standard-pattern-names-for-generation.rst: New file.
* doc/gccint/machine-descriptions/when-the-order-of-patterns-matters.rst: New file.
* doc/gccint/makefile-fragments.rst: New file.
* doc/gccint/match-and-simplify.rst: New file.
* doc/gccint/memory-management-and-type-information.rst: New file.
* doc/gccint/memory-management-and-type-information/how-to-invoke-the-garbage-collector.rst:
New file.
* doc/gccint/memory-management-and-type-information/marking-roots-for-the-garbage-collector.rst:
New file.
* doc/gccint/memory-management-and-type-information/source-files-containing-type-information.rst:
New file.
* doc/gccint/memory-management-and-type-information/support-for-inheritance.rst: New file.
* doc/gccint/memory-management-and-type-information/support-for-user-provided-gc-marking-routines.rst:
New file.
* doc/gccint/memory-management-and-type-information/the-inside-of-a-gty.rst: New file.
* doc/gccint/memory-management-and-type-information/troubleshooting-the-garbage-collector.rst:
New file.
* doc/gccint/option-file-format.rst: New file.
* doc/gccint/option-properties.rst: New file.
* doc/gccint/option-specification-files.rst: New file.
* doc/gccint/passes-and-files-of-the-compiler.rst: New file.
* doc/gccint/passes-and-files-of-the-compiler/gimplification-pass.rst: New file.
* doc/gccint/passes-and-files-of-the-compiler/inter-procedural-optimization-passes.rst:
New file.
* doc/gccint/passes-and-files-of-the-compiler/optimization-info.rst: New file.
* doc/gccint/passes-and-files-of-the-compiler/parsing-pass.rst: New file.
* doc/gccint/passes-and-files-of-the-compiler/pass-manager.rst: New file.
* doc/gccint/passes-and-files-of-the-compiler/rtl-passes.rst: New file.
* doc/gccint/passes-and-files-of-the-compiler/tree-ssa-passes.rst: New file.
* doc/gccint/plugins.rst: New file.
* doc/gccint/plugins/building-gcc-plugins.rst: New file.
* doc/gccint/plugins/controlling-which-passes-are-being-run.rst: New file.
* doc/gccint/plugins/giving-information-about-a-plugin.rst: New file.
* doc/gccint/plugins/interacting-with-the-gcc-garbage-collector.rst: New file.
* doc/gccint/plugins/interacting-with-the-pass-manager.rst: New file.
* doc/gccint/plugins/keeping-track-of-available-passes.rst: New file.
* doc/gccint/plugins/loading-plugins.rst: New file.
* doc/gccint/plugins/plugin-api.rst: New file.
* doc/gccint/plugins/recording-information-about-pass-execution.rst: New file.
* doc/gccint/plugins/registering-custom-attributes-or-pragmas.rst: New file.
* doc/gccint/rtl-representation.rst: New file.
* doc/gccint/rtl-representation/access-to-operands.rst: New file.
* doc/gccint/rtl-representation/access-to-special-operands.rst: New file.
* doc/gccint/rtl-representation/assembler-instructions-as-expressions.rst: New file.
* doc/gccint/rtl-representation/bit-fields.rst: New file.
* doc/gccint/rtl-representation/comparison-operations.rst: New file.
* doc/gccint/rtl-representation/constant-expression-types.rst: New file.
* doc/gccint/rtl-representation/conversions.rst: New file.
* doc/gccint/rtl-representation/declarations.rst: New file.
* doc/gccint/rtl-representation/embedded-side-effects-on-addresses.rst: New file.
* doc/gccint/rtl-representation/flags-in-an-rtl-expression.rst: New file.
* doc/gccint/rtl-representation/insns.rst: New file.
* doc/gccint/rtl-representation/machine-modes.rst: New file.
* doc/gccint/rtl-representation/on-the-side-ssa-form-for-rtl.rst: New file.
* doc/gccint/rtl-representation/reading-rtl.rst: New file.
* doc/gccint/rtl-representation/registers-and-memory.rst: New file.
* doc/gccint/rtl-representation/rtl-classes-and-formats.rst: New file.
* doc/gccint/rtl-representation/rtl-expressions-for-arithmetic.rst: New file.
* doc/gccint/rtl-representation/rtl-object-types.rst: New file.
* doc/gccint/rtl-representation/rtl-representation-of-function-call-insns.rst: New file.
* doc/gccint/rtl-representation/side-effect-expressions.rst: New file.
* doc/gccint/rtl-representation/structure-sharing-assumptions.rst: New file.
* doc/gccint/rtl-representation/variable-location-debug-information-in-rtl.rst: New file.
* doc/gccint/rtl-representation/vector-operations.rst: New file.
* doc/gccint/sizes-and-offsets-as-runtime-invariants.rst: New file.
* doc/gccint/sizes-and-offsets-as-runtime-invariants/alignment-of-polyints.rst: New file.
* doc/gccint/sizes-and-offsets-as-runtime-invariants/arithmetic-on-polyints.rst: New file.
* doc/gccint/sizes-and-offsets-as-runtime-invariants/comparisons-involving-polyint.rst:
New file.
* doc/gccint/sizes-and-offsets-as-runtime-invariants/computing-bounds-on-polyints.rst:
New file.
* doc/gccint/sizes-and-offsets-as-runtime-invariants/consequences-of-using-polyint.rst:
New file.
* doc/gccint/sizes-and-offsets-as-runtime-invariants/converting-polyints.rst: New file.
* doc/gccint/sizes-and-offsets-as-runtime-invariants/guidelines-for-using-polyint.rst:
New file.
* doc/gccint/sizes-and-offsets-as-runtime-invariants/miscellaneous-polyint-routines.rst:
New file.
* doc/gccint/sizes-and-offsets-as-runtime-invariants/overview-of-polyint.rst: New file.
* doc/gccint/source-tree-structure-and-build-system.rst: New file.
* doc/gccint/source-tree-structure-and-build-system/configure-terms-and-history.rst:
New file.
* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory.rst: New file.
* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/anatomy-of-a-language-front-end.rst:
New file.
* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/anatomy-of-a-target-back-end.rst:
New file.
* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/build-system-in-the-gcc-directory.rst:
New file.
* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/building-documentation.rst:
New file.
* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/configuration-in-the-gcc-directory.rst:
New file.
* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/headers-installed-by-gcc.rst:
New file.
* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/library-source-files-and-headers-under-the-gcc-directory.rst:
New file.
* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/makefile-targets.rst:
New file.
* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/subdirectories-of-gcc.rst:
New file.
* doc/gccint/source-tree-structure-and-build-system/top-level-source-directory.rst:
New file.
* doc/gccint/standard-header-file-directories.rst: New file.
* doc/gccint/static-analyzer.rst: New file.
* doc/gccint/target-macros.rst: New file.
* doc/gccint/target-macros/adding-support-for-named-address-spaces.rst: New file.
* doc/gccint/target-macros/addressing-modes.rst: New file.
* doc/gccint/target-macros/adjusting-the-instruction-scheduler.rst: New file.
* doc/gccint/target-macros/anchored-addresses.rst: New file.
* doc/gccint/target-macros/c++-abi-parameters.rst: New file.
* doc/gccint/target-macros/condition-code-status.rst: New file.
* doc/gccint/target-macros/controlling-debugging-information-format.rst: New file.
* doc/gccint/target-macros/controlling-the-compilation-driver-gcc.rst: New file.
* doc/gccint/target-macros/cross-compilation-and-floating-point.rst: New file.
* doc/gccint/target-macros/d-abi-parameters.rst: New file.
* doc/gccint/target-macros/defining-coprocessor-specifics-for-mips-targets.rst: New file.
* doc/gccint/target-macros/defining-data-structures-for-per-function-information.rst:
New file.
* doc/gccint/target-macros/defining-target-specific-uses-of-attribute.rst: New file.
* doc/gccint/target-macros/defining-the-output-assembler-language.rst: New file.
* doc/gccint/target-macros/defining-the-output-assembler-language/assembler-commands-for-alignment.rst:
New file.
* doc/gccint/target-macros/defining-the-output-assembler-language/assembler-commands-for-exception-regions.rst:
New file.
* doc/gccint/target-macros/defining-the-output-assembler-language/how-initialization-functions-are-handled.rst:
New file.
* doc/gccint/target-macros/defining-the-output-assembler-language/macros-controlling-initialization-routines.rst:
New file.
* doc/gccint/target-macros/defining-the-output-assembler-language/output-and-generation-of-labels.rst:
New file.
* doc/gccint/target-macros/defining-the-output-assembler-language/output-of-assembler-instructions.rst:
New file.
* doc/gccint/target-macros/defining-the-output-assembler-language/output-of-data.rst:
New file.
* doc/gccint/target-macros/defining-the-output-assembler-language/output-of-dispatch-tables.rst:
New file.
* doc/gccint/target-macros/defining-the-output-assembler-language/output-of-uninitialized-variables.rst:
New file.
* doc/gccint/target-macros/defining-the-output-assembler-language/the-overall-framework-of-an-assembler-file.rst:
New file.
* doc/gccint/target-macros/describing-relative-costs-of-operations.rst: New file.
* doc/gccint/target-macros/dividing-the-output-into-sections-texts-data.rst: New file.
* doc/gccint/target-macros/emulating-tls.rst: New file.
* doc/gccint/target-macros/implementing-the-varargs-macros.rst: New file.
* doc/gccint/target-macros/implicit-calls-to-library-routines.rst: New file.
* doc/gccint/target-macros/layout-of-source-language-data-types.rst: New file.
* doc/gccint/target-macros/miscellaneous-parameters.rst: New file.
* doc/gccint/target-macros/mode-switching-instructions.rst: New file.
* doc/gccint/target-macros/parameters-for-precompiled-header-validity-checking.rst:
New file.
* doc/gccint/target-macros/position-independent-code.rst: New file.
* doc/gccint/target-macros/register-classes.rst: New file.
* doc/gccint/target-macros/register-usage.rst: New file.
* doc/gccint/target-macros/run-time-target-specification.rst: New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions.rst: New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/basic-stack-layout.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/caller-saves-register-allocation.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/eliminating-frame-pointer-and-arg-pointer.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/exception-handling-support.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/function-entry-and-exit.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/generating-code-for-profiling.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/how-large-values-are-returned.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/how-scalar-function-values-are-returned.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/miscellaneous-register-hooks.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/passing-arguments-in-registers.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/passing-function-arguments-on-the-stack.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/permitting-tail-calls.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/registers-that-address-the-stack-frame.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/shrink-wrapping-separate-components.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/specifying-how-stack-checking-is-done.rst:
New file.
* doc/gccint/target-macros/stack-layout-and-calling-conventions/stack-smashing-protection.rst:
New file.
* doc/gccint/target-macros/storage-layout.rst: New file.
* doc/gccint/target-macros/support-for-nested-functions.rst: New file.
* doc/gccint/target-macros/the-global-targetm-variable.rst: New file.
* doc/gccint/target-makefile-fragments.rst: New file.
* doc/gccint/testsuites.rst: New test.
* doc/gccint/testsuites/ada-language-testsuites.rst: New test.
* doc/gccint/testsuites/c-language-testsuites.rst: New test.
* doc/gccint/testsuites/directives-used-within-dejagnu-tests.rst: New test.
* doc/gccint/testsuites/directives-used-within-dejagnu-tests/commands-for-use-in-dg-final.rst:
New test.
* doc/gccint/testsuites/directives-used-within-dejagnu-tests/features-for-dg-add-options.rst:
New test.
* doc/gccint/testsuites/directives-used-within-dejagnu-tests/keywords-describing-target-attributes.rst:
New test.
* doc/gccint/testsuites/directives-used-within-dejagnu-tests/selecting-targets-to-which-a-test-applies.rst:
New test.
* doc/gccint/testsuites/directives-used-within-dejagnu-tests/syntax-and-descriptions-of-test-directives.rst:
New test.
* doc/gccint/testsuites/directives-used-within-dejagnu-tests/variants-of-dg-require-support.rst:
New test.
* doc/gccint/testsuites/idioms-used-in-testsuite-code.rst: New test.
* doc/gccint/testsuites/support-for-testing-binary-compatibility.rst: New test.
* doc/gccint/testsuites/support-for-testing-gcov.rst: New test.
* doc/gccint/testsuites/support-for-testing-gimple-passes.rst: New test.
* doc/gccint/testsuites/support-for-testing-link-time-optimizations.rst: New test.
* doc/gccint/testsuites/support-for-testing-profile-directed-optimizations.rst: New test.
* doc/gccint/testsuites/support-for-testing-rtl-passes.rst: New test.
* doc/gccint/testsuites/support-for-torture-testing-using-multiple-options.rst: New test.
* doc/gccint/the-gcc-low-level-runtime-library.rst: New file.
* doc/gccint/the-gcc-low-level-runtime-library/language-independent-routines-for-exception-handling.rst:
New file.
* doc/gccint/the-gcc-low-level-runtime-library/miscellaneous-runtime-library-routines.rst:
New file.
* doc/gccint/the-gcc-low-level-runtime-library/routines-for-decimal-floating-point-emulation.rst:
New file.
* doc/gccint/the-gcc-low-level-runtime-library/routines-for-fixed-point-fractional-emulation.rst:
New file.
* doc/gccint/the-gcc-low-level-runtime-library/routines-for-floating-point-emulation.rst:
New file.
* doc/gccint/the-gcc-low-level-runtime-library/routines-for-integer-arithmetic.rst:
New file.
* doc/gccint/the-language.rst: New file.
* doc/gccint/user-experience-guidelines.rst: New file.
* doc/install/binaries.rst: New file.
* doc/install/building.rst: New file.
* doc/install/building/building-a-cross-compiler.rst: New file.
* doc/install/building/building-a-native-compiler.rst: New file.
* doc/install/building/building-in-parallel.rst: New file.
* doc/install/building/building-the-ada-compiler.rst: New file.
* doc/install/building/building-the-d-compiler.rst: New file.
* doc/install/building/building-with-profile-feedback.rst: New file.
* doc/install/conf.py: New file.
* doc/install/configuration.rst: New file.
* doc/install/copyright.rst: New file.
* doc/install/downloading-gcc.rst: New file.
* doc/install/final-installation.rst: New file.
* doc/install/gnu-free-documentation-license.rst: New file.
* doc/install/host-target-specific-installation-notes-for-gcc.rst: New file.
* doc/install/how-can-you-run-the-testsuite-on-selected-tests.rst: New test.
* doc/install/how-to-interpret-test-results.rst: New file.
* doc/install/index.rst: New file.
* doc/install/indices-and-tables.rst: New file.
* doc/install/installing-gcc.rst: New file.
* doc/install/passing-options-and-running-multiple-testsuites.rst: New test.
* doc/install/prerequisites.rst: New file.
* doc/install/submitting-test-results.rst: New file.
* doc/install/testing.rst: New file.
gcc/fortran/ChangeLog:
* doc/gfc-internals/code-that-interacts-with-the-user.rst: New file.
* doc/gfc-internals/command-line-options.rst: New file.
* doc/gfc-internals/conf.py: New file.
* doc/gfc-internals/copyright.rst: New file.
* doc/gfc-internals/error-handling.rst: New file.
* doc/gfc-internals/frontend-data-structures.rst: New file.
* doc/gfc-internals/generating-the-intermediate-language-for-later-stages.rst: New file.
* doc/gfc-internals/generating-the-intermediate-language-for-later-stages/accessing-declarations.rst:
New file.
* doc/gfc-internals/generating-the-intermediate-language-for-later-stages/basic-data-structures.rst:
New file.
* doc/gfc-internals/generating-the-intermediate-language-for-later-stages/converting-expressions-to-tree.rst:
New file.
* doc/gfc-internals/generating-the-intermediate-language-for-later-stages/translating-statements.rst:
New file.
* doc/gfc-internals/gfccode.rst: New file.
* doc/gfc-internals/gfcexpr.rst: New file.
* doc/gfc-internals/gnu-free-documentation-license.rst: New file.
* doc/gfc-internals/index.rst: New file.
* doc/gfc-internals/indices-and-tables.rst: New file.
* doc/gfc-internals/internals-of-fortran-2003-oop-features.rst: New file.
* doc/gfc-internals/introduction.rst: New file.
* doc/gfc-internals/symbol-versioning.rst: New file.
* doc/gfc-internals/the-libgfortran-runtime-library.rst: New file.
* doc/gfc-internals/type-bound-operators.rst: New file.
* doc/gfc-internals/type-bound-procedures.rst: New file.
* doc/gfortran/about-gnu-fortran.rst: New file.
* doc/gfortran/coarray-programming.rst: New file.
* doc/gfortran/compiler-characteristics.rst: New file.
* doc/gfortran/compiler-characteristics/asynchronous-i-o.rst: New file.
* doc/gfortran/compiler-characteristics/data-consistency-and-durability.rst: New file.
* doc/gfortran/compiler-characteristics/evaluation-of-logical-expressions.rst: New file.
* doc/gfortran/compiler-characteristics/file-format-of-unformatted-sequential-files.rst:
New file.
* doc/gfortran/compiler-characteristics/file-operations-on-symbolic-links.rst: New file.
* doc/gfortran/compiler-characteristics/files-opened-without-an-explicit-action=-specifier.rst:
New file.
* doc/gfortran/compiler-characteristics/internal-representation-of-logical-variables.rst:
New file.
* doc/gfortran/compiler-characteristics/kind-type-parameters.rst: New file.
* doc/gfortran/compiler-characteristics/max-and-min-intrinsics-with-real-nan-arguments.rst:
New file.
* doc/gfortran/compiler-characteristics/thread-safety-of-the-runtime-library.rst: New file.
* doc/gfortran/conf.py: New file.
* doc/gfortran/contributing.rst: New file.
* doc/gfortran/contributors-to-gnu-fortran.rst: New file.
* doc/gfortran/copyright.rst: New file.
* doc/gfortran/extensions-implemented-in-gnu-fortran.rst: New file.
* doc/gfortran/extensions-not-implemented-in-gnu-fortran.rst: New file.
* doc/gfortran/extensions.rst: New file.
* doc/gfortran/function-abi-documentation.rst: New file.
* doc/gfortran/funding.rst: New file.
* doc/gfortran/general-public-license-3.rst: New file.
* doc/gfortran/gnu-fortran-and-gcc.rst: New file.
* doc/gfortran/gnu-fortran-command-options.rst: New file.
* doc/gfortran/gnu-fortran-command-options/description.rst: New file.
* doc/gfortran/gnu-fortran-command-options/enable-and-customize-preprocessing.rst: New file.
* doc/gfortran/gnu-fortran-command-options/environment-variables-affecting-gfortran.rst:
New file.
* doc/gfortran/gnu-fortran-command-options/influencing-runtime-behavior.rst: New file.
* doc/gfortran/gnu-fortran-command-options/influencing-the-linking-step.rst: New file.
* doc/gfortran/gnu-fortran-command-options/option-summary.rst: New file.
* doc/gfortran/gnu-fortran-command-options/options-controlling-fortran-dialect.rst:
New file.
* doc/gfortran/gnu-fortran-command-options/options-for-code-generation-conventions.rst:
New file.
* doc/gfortran/gnu-fortran-command-options/options-for-debugging-your-program-or-gnu-fortran.rst:
New file.
* doc/gfortran/gnu-fortran-command-options/options-for-directory-search.rst: New file.
* doc/gfortran/gnu-fortran-command-options/options-for-interoperability-with-other-languages.rst:
New file.
* doc/gfortran/gnu-fortran-command-options/options-to-request-or-suppress-errors-and-warnings.rst:
New file.
* doc/gfortran/gnu-fortran-compiler-directives.rst: New file.
* doc/gfortran/gnu-free-documentation-license.rst: New file.
* doc/gfortran/index.rst: New file.
* doc/gfortran/indices-and-tables.rst: New file.
* doc/gfortran/interoperability-with-c.rst: New file.
* doc/gfortran/intrinsic-modules.rst: New file.
* doc/gfortran/intrinsic-modules/ieee-modules-ieeeexceptions-ieeearithmetic-and-ieeefeatures.rst:
New file.
* doc/gfortran/intrinsic-modules/isocbinding.rst: New file.
* doc/gfortran/intrinsic-modules/isofortranenv.rst: New file.
* doc/gfortran/intrinsic-modules/openacc-module-openacc.rst: New file.
* doc/gfortran/intrinsic-modules/openmp-modules-omplib-and-omplibkinds.rst: New file.
* doc/gfortran/intrinsic-procedures.rst: New file.
* doc/gfortran/intrinsic-procedures/abort.rst: New file.
* doc/gfortran/intrinsic-procedures/abs.rst: New file.
* doc/gfortran/intrinsic-procedures/access.rst: New file.
* doc/gfortran/intrinsic-procedures/achar.rst: New file.
* doc/gfortran/intrinsic-procedures/acos.rst: New file.
* doc/gfortran/intrinsic-procedures/acosd.rst: New file.
* doc/gfortran/intrinsic-procedures/acosh.rst: New file.
* doc/gfortran/intrinsic-procedures/adjustl.rst: New file.
* doc/gfortran/intrinsic-procedures/adjustr.rst: New file.
* doc/gfortran/intrinsic-procedures/aimag.rst: New file.
* doc/gfortran/intrinsic-procedures/aint.rst: New file.
* doc/gfortran/intrinsic-procedures/alarm.rst: New file.
* doc/gfortran/intrinsic-procedures/all.rst: New file.
* doc/gfortran/intrinsic-procedures/allocated.rst: New file.
* doc/gfortran/intrinsic-procedures/and.rst: New file.
* doc/gfortran/intrinsic-procedures/anint.rst: New file.
* doc/gfortran/intrinsic-procedures/any.rst: New file.
* doc/gfortran/intrinsic-procedures/asin.rst: New file.
* doc/gfortran/intrinsic-procedures/asind.rst: New file.
* doc/gfortran/intrinsic-procedures/asinh.rst: New file.
* doc/gfortran/intrinsic-procedures/associated.rst: New file.
* doc/gfortran/intrinsic-procedures/atan.rst: New file.
* doc/gfortran/intrinsic-procedures/atan2.rst: New file.
* doc/gfortran/intrinsic-procedures/atan2d.rst: New file.
* doc/gfortran/intrinsic-procedures/atand.rst: New file.
* doc/gfortran/intrinsic-procedures/atanh.rst: New file.
* doc/gfortran/intrinsic-procedures/atomicadd.rst: New file.
* doc/gfortran/intrinsic-procedures/atomicand.rst: New file.
* doc/gfortran/intrinsic-procedures/atomiccas.rst: New file.
* doc/gfortran/intrinsic-procedures/atomicdefine.rst: New file.
* doc/gfortran/intrinsic-procedures/atomicfetchadd.rst: New file.
* doc/gfortran/intrinsic-procedures/atomicfetchand.rst: New file.
* doc/gfortran/intrinsic-procedures/atomicfetchor.rst: New file.
* doc/gfortran/intrinsic-procedures/atomicfetchxor.rst: New file.
* doc/gfortran/intrinsic-procedures/atomicor.rst: New file.
* doc/gfortran/intrinsic-procedures/atomicref.rst: New file.
* doc/gfortran/intrinsic-procedures/atomicxor.rst: New file.
* doc/gfortran/intrinsic-procedures/backtrace.rst: New file.
* doc/gfortran/intrinsic-procedures/besselj0.rst: New file.
* doc/gfortran/intrinsic-procedures/besselj1.rst: New file.
* doc/gfortran/intrinsic-procedures/besseljn.rst: New file.
* doc/gfortran/intrinsic-procedures/bessely0.rst: New file.
* doc/gfortran/intrinsic-procedures/bessely1.rst: New file.
* doc/gfortran/intrinsic-procedures/besselyn.rst: New file.
* doc/gfortran/intrinsic-procedures/bge.rst: New file.
* doc/gfortran/intrinsic-procedures/bgt.rst: New file.
* doc/gfortran/intrinsic-procedures/bitsize.rst: New file.
* doc/gfortran/intrinsic-procedures/ble.rst: New file.
* doc/gfortran/intrinsic-procedures/blt.rst: New file.
* doc/gfortran/intrinsic-procedures/btest.rst: New file.
* doc/gfortran/intrinsic-procedures/cassociated.rst: New file.
* doc/gfortran/intrinsic-procedures/ceiling.rst: New file.
* doc/gfortran/intrinsic-procedures/cfpointer.rst: New file.
* doc/gfortran/intrinsic-procedures/cfprocpointer.rst: New file.
* doc/gfortran/intrinsic-procedures/cfunloc.rst: New file.
* doc/gfortran/intrinsic-procedures/char.rst: New file.
* doc/gfortran/intrinsic-procedures/chdir.rst: New file.
* doc/gfortran/intrinsic-procedures/chmod.rst: New file.
* doc/gfortran/intrinsic-procedures/cloc.rst: New file.
* doc/gfortran/intrinsic-procedures/cmplx.rst: New file.
* doc/gfortran/intrinsic-procedures/cobroadcast.rst: New file.
* doc/gfortran/intrinsic-procedures/comax.rst: New file.
* doc/gfortran/intrinsic-procedures/comin.rst: New file.
* doc/gfortran/intrinsic-procedures/commandargumentcount.rst: New file.
* doc/gfortran/intrinsic-procedures/compileroptions.rst: New file.
* doc/gfortran/intrinsic-procedures/compilerversion.rst: New file.
* doc/gfortran/intrinsic-procedures/complex.rst: New file.
* doc/gfortran/intrinsic-procedures/conjg.rst: New file.
* doc/gfortran/intrinsic-procedures/coreduce.rst: New file.
* doc/gfortran/intrinsic-procedures/cos.rst: New file.
* doc/gfortran/intrinsic-procedures/cosd.rst: New file.
* doc/gfortran/intrinsic-procedures/cosh.rst: New file.
* doc/gfortran/intrinsic-procedures/cosum.rst: New file.
* doc/gfortran/intrinsic-procedures/cotan.rst: New file.
* doc/gfortran/intrinsic-procedures/cotand.rst: New file.
* doc/gfortran/intrinsic-procedures/count.rst: New file.
* doc/gfortran/intrinsic-procedures/cputime.rst: New file.
* doc/gfortran/intrinsic-procedures/cshift.rst: New file.
* doc/gfortran/intrinsic-procedures/csizeof.rst: New file.
* doc/gfortran/intrinsic-procedures/ctime.rst: New file.
* doc/gfortran/intrinsic-procedures/dateandtime.rst: New file.
* doc/gfortran/intrinsic-procedures/dble.rst: New file.
* doc/gfortran/intrinsic-procedures/dcmplx.rst: New file.
* doc/gfortran/intrinsic-procedures/digits.rst: New file.
* doc/gfortran/intrinsic-procedures/dim.rst: New file.
* doc/gfortran/intrinsic-procedures/dotproduct.rst: New file.
* doc/gfortran/intrinsic-procedures/dprod.rst: New file.
* doc/gfortran/intrinsic-procedures/dreal.rst: New file.
* doc/gfortran/intrinsic-procedures/dshiftl.rst: New file.
* doc/gfortran/intrinsic-procedures/dshiftr.rst: New file.
* doc/gfortran/intrinsic-procedures/dtime.rst: New file.
* doc/gfortran/intrinsic-procedures/eoshift.rst: New file.
* doc/gfortran/intrinsic-procedures/epsilon.rst: New file.
* doc/gfortran/intrinsic-procedures/erf.rst: New file.
* doc/gfortran/intrinsic-procedures/erfc.rst: New file.
* doc/gfortran/intrinsic-procedures/erfcscaled.rst: New file.
* doc/gfortran/intrinsic-procedures/etime.rst: New file.
* doc/gfortran/intrinsic-procedures/eventquery.rst: New file.
* doc/gfortran/intrinsic-procedures/executecommandline.rst: New file.
* doc/gfortran/intrinsic-procedures/exit.rst: New file.
* doc/gfortran/intrinsic-procedures/exp.rst: New file.
* doc/gfortran/intrinsic-procedures/exponent.rst: New file.
* doc/gfortran/intrinsic-procedures/extendstypeof.rst: New file.
* doc/gfortran/intrinsic-procedures/fdate.rst: New file.
* doc/gfortran/intrinsic-procedures/fget.rst: New file.
* doc/gfortran/intrinsic-procedures/fgetc.rst: New file.
* doc/gfortran/intrinsic-procedures/findloc.rst: New file.
* doc/gfortran/intrinsic-procedures/floor.rst: New file.
* doc/gfortran/intrinsic-procedures/flush.rst: New file.
* doc/gfortran/intrinsic-procedures/fnum.rst: New file.
* doc/gfortran/intrinsic-procedures/fput.rst: New file.
* doc/gfortran/intrinsic-procedures/fputc.rst: New file.
* doc/gfortran/intrinsic-procedures/fraction.rst: New file.
* doc/gfortran/intrinsic-procedures/free.rst: New file.
* doc/gfortran/intrinsic-procedures/fseek.rst: New file.
* doc/gfortran/intrinsic-procedures/fstat.rst: New file.
* doc/gfortran/intrinsic-procedures/ftell.rst: New file.
* doc/gfortran/intrinsic-procedures/gamma.rst: New file.
* doc/gfortran/intrinsic-procedures/gerror.rst: New file.
* doc/gfortran/intrinsic-procedures/getarg.rst: New file.
* doc/gfortran/intrinsic-procedures/getcommand.rst: New file.
* doc/gfortran/intrinsic-procedures/getcommandargument.rst: New file.
* doc/gfortran/intrinsic-procedures/getcwd.rst: New file.
* doc/gfortran/intrinsic-procedures/getenv.rst: New file.
* doc/gfortran/intrinsic-procedures/getenvironmentvariable.rst: New file.
* doc/gfortran/intrinsic-procedures/getgid.rst: New file.
* doc/gfortran/intrinsic-procedures/getlog.rst: New file.
* doc/gfortran/intrinsic-procedures/getpid.rst: New file.
* doc/gfortran/intrinsic-procedures/getuid.rst: New file.
* doc/gfortran/intrinsic-procedures/gmtime.rst: New file.
* doc/gfortran/intrinsic-procedures/hostnm.rst: New file.
* doc/gfortran/intrinsic-procedures/huge.rst: New file.
* doc/gfortran/intrinsic-procedures/hypot.rst: New file.
* doc/gfortran/intrinsic-procedures/iachar.rst: New file.
* doc/gfortran/intrinsic-procedures/iall.rst: New file.
* doc/gfortran/intrinsic-procedures/iand.rst: New file.
* doc/gfortran/intrinsic-procedures/iany.rst: New file.
* doc/gfortran/intrinsic-procedures/iargc.rst: New file.
* doc/gfortran/intrinsic-procedures/ibclr.rst: New file.
* doc/gfortran/intrinsic-procedures/ibits.rst: New file.
* doc/gfortran/intrinsic-procedures/ibset.rst: New file.
* doc/gfortran/intrinsic-procedures/ichar.rst: New file.
* doc/gfortran/intrinsic-procedures/idate.rst: New file.
* doc/gfortran/intrinsic-procedures/ieor.rst: New file.
* doc/gfortran/intrinsic-procedures/ierrno.rst: New file.
* doc/gfortran/intrinsic-procedures/imageindex.rst: New file.
* doc/gfortran/intrinsic-procedures/index.rst: New file.
* doc/gfortran/intrinsic-procedures/int.rst: New file.
* doc/gfortran/intrinsic-procedures/int2.rst: New file.
* doc/gfortran/intrinsic-procedures/int8.rst: New file.
* doc/gfortran/intrinsic-procedures/introduction-to-intrinsic-procedures.rst: New file.
* doc/gfortran/intrinsic-procedures/ior.rst: New file.
* doc/gfortran/intrinsic-procedures/iparity.rst: New file.
* doc/gfortran/intrinsic-procedures/irand.rst: New file.
* doc/gfortran/intrinsic-procedures/isatty.rst: New file.
* doc/gfortran/intrinsic-procedures/iscontiguous.rst: New file.
* doc/gfortran/intrinsic-procedures/ishft.rst: New file.
* doc/gfortran/intrinsic-procedures/ishftc.rst: New file.
* doc/gfortran/intrinsic-procedures/isiostatend.rst: New file.
* doc/gfortran/intrinsic-procedures/isiostateor.rst: New file.
* doc/gfortran/intrinsic-procedures/isnan.rst: New file.
* doc/gfortran/intrinsic-procedures/itime.rst: New file.
* doc/gfortran/intrinsic-procedures/kill.rst: New file.
* doc/gfortran/intrinsic-procedures/kind.rst: New file.
* doc/gfortran/intrinsic-procedures/lbound.rst: New file.
* doc/gfortran/intrinsic-procedures/lcobound.rst: New file.
* doc/gfortran/intrinsic-procedures/leadz.rst: New file.
* doc/gfortran/intrinsic-procedures/len.rst: New file.
* doc/gfortran/intrinsic-procedures/lentrim.rst: New file.
* doc/gfortran/intrinsic-procedures/lge.rst: New file.
* doc/gfortran/intrinsic-procedures/lgt.rst: New file.
* doc/gfortran/intrinsic-procedures/link.rst: New file.
* doc/gfortran/intrinsic-procedures/lle.rst: New file.
* doc/gfortran/intrinsic-procedures/llt.rst: New file.
* doc/gfortran/intrinsic-procedures/lnblnk.rst: New file.
* doc/gfortran/intrinsic-procedures/loc.rst: New file.
* doc/gfortran/intrinsic-procedures/log.rst: New file.
* doc/gfortran/intrinsic-procedures/log10.rst: New file.
* doc/gfortran/intrinsic-procedures/loggamma.rst: New file.
* doc/gfortran/intrinsic-procedures/logical.rst: New file.
* doc/gfortran/intrinsic-procedures/lshift.rst: New file.
* doc/gfortran/intrinsic-procedures/lstat.rst: New file.
* doc/gfortran/intrinsic-procedures/ltime.rst: New file.
* doc/gfortran/intrinsic-procedures/malloc.rst: New file.
* doc/gfortran/intrinsic-procedures/maskl.rst: New file.
* doc/gfortran/intrinsic-procedures/maskr.rst: New file.
* doc/gfortran/intrinsic-procedures/matmul.rst: New file.
* doc/gfortran/intrinsic-procedures/max.rst: New file.
* doc/gfortran/intrinsic-procedures/maxexponent.rst: New file.
* doc/gfortran/intrinsic-procedures/maxloc.rst: New file.
* doc/gfortran/intrinsic-procedures/maxval.rst: New file.
* doc/gfortran/intrinsic-procedures/mclock.rst: New file.
* doc/gfortran/intrinsic-procedures/mclock8.rst: New file.
* doc/gfortran/intrinsic-procedures/merge.rst: New file.
* doc/gfortran/intrinsic-procedures/mergebits.rst: New file.
* doc/gfortran/intrinsic-procedures/min.rst: New file.
* doc/gfortran/intrinsic-procedures/minexponent.rst: New file.
* doc/gfortran/intrinsic-procedures/minloc.rst: New file.
* doc/gfortran/intrinsic-procedures/minval.rst: New file.
* doc/gfortran/intrinsic-procedures/mod.rst: New file.
* doc/gfortran/intrinsic-procedures/modulo.rst: New file.
* doc/gfortran/intrinsic-procedures/movealloc.rst: New file.
* doc/gfortran/intrinsic-procedures/mvbits.rst: New file.
* doc/gfortran/intrinsic-procedures/nearest.rst: New file.
* doc/gfortran/intrinsic-procedures/newline.rst: New file.
* doc/gfortran/intrinsic-procedures/nint.rst: New file.
* doc/gfortran/intrinsic-procedures/norm2.rst: New file.
* doc/gfortran/intrinsic-procedures/not.rst: New file.
* doc/gfortran/intrinsic-procedures/null.rst: New file.
* doc/gfortran/intrinsic-procedures/numimages.rst: New file.
* doc/gfortran/intrinsic-procedures/or.rst: New file.
* doc/gfortran/intrinsic-procedures/pack.rst: New file.
* doc/gfortran/intrinsic-procedures/parity.rst: New file.
* doc/gfortran/intrinsic-procedures/perror.rst: New file.
* doc/gfortran/intrinsic-procedures/popcnt.rst: New file.
* doc/gfortran/intrinsic-procedures/poppar.rst: New file.
* doc/gfortran/intrinsic-procedures/precision.rst: New file.
* doc/gfortran/intrinsic-procedures/present.rst: New file.
* doc/gfortran/intrinsic-procedures/product.rst: New file.
* doc/gfortran/intrinsic-procedures/radix.rst: New file.
* doc/gfortran/intrinsic-procedures/ran.rst: New file.
* doc/gfortran/intrinsic-procedures/rand.rst: New file.
* doc/gfortran/intrinsic-procedures/randominit.rst: New file.
* doc/gfortran/intrinsic-procedures/randomnumber.rst: New file.
* doc/gfortran/intrinsic-procedures/randomseed.rst: New file.
* doc/gfortran/intrinsic-procedures/range.rst: New file.
* doc/gfortran/intrinsic-procedures/rank.rst: New file.
* doc/gfortran/intrinsic-procedures/real.rst: New file.
* doc/gfortran/intrinsic-procedures/rename.rst: New file.
* doc/gfortran/intrinsic-procedures/repeat.rst: New file.
* doc/gfortran/intrinsic-procedures/reshape.rst: New file.
* doc/gfortran/intrinsic-procedures/rrspacing.rst: New file.
* doc/gfortran/intrinsic-procedures/rshift.rst: New file.
* doc/gfortran/intrinsic-procedures/sametypeas.rst: New file.
* doc/gfortran/intrinsic-procedures/scale.rst: New file.
* doc/gfortran/intrinsic-procedures/scan.rst: New file.
* doc/gfortran/intrinsic-procedures/secnds.rst: New file.
* doc/gfortran/intrinsic-procedures/second.rst: New file.
* doc/gfortran/intrinsic-procedures/selectedcharkind.rst: New file.
* doc/gfortran/intrinsic-procedures/selectedintkind.rst: New file.
* doc/gfortran/intrinsic-procedures/selectedrealkind.rst: New file.
* doc/gfortran/intrinsic-procedures/setexponent.rst: New file.
* doc/gfortran/intrinsic-procedures/shape.rst: New file.
* doc/gfortran/intrinsic-procedures/shifta.rst: New file.
* doc/gfortran/intrinsic-procedures/shiftl.rst: New file.
* doc/gfortran/intrinsic-procedures/shiftr.rst: New file.
* doc/gfortran/intrinsic-procedures/sign.rst: New file.
* doc/gfortran/intrinsic-procedures/signal.rst: New file.
* doc/gfortran/intrinsic-procedures/sin.rst: New file.
* doc/gfortran/intrinsic-procedures/sind.rst: New file.
* doc/gfortran/intrinsic-procedures/sinh.rst: New file.
* doc/gfortran/intrinsic-procedures/size.rst: New file.
* doc/gfortran/intrinsic-procedures/sizeof.rst: New file.
* doc/gfortran/intrinsic-procedures/sleep.rst: New file.
* doc/gfortran/intrinsic-procedures/spacing.rst: New file.
* doc/gfortran/intrinsic-procedures/spread.rst: New file.
* doc/gfortran/intrinsic-procedures/sqrt.rst: New file.
* doc/gfortran/intrinsic-procedures/srand.rst: New file.
* doc/gfortran/intrinsic-procedures/stat.rst: New file.
* doc/gfortran/intrinsic-procedures/storagesize.rst: New file.
* doc/gfortran/intrinsic-procedures/sum.rst: New file.
* doc/gfortran/intrinsic-procedures/symlnk.rst: New file.
* doc/gfortran/intrinsic-procedures/system.rst: New file.
* doc/gfortran/intrinsic-procedures/systemclock.rst: New file.
* doc/gfortran/intrinsic-procedures/tan.rst: New file.
* doc/gfortran/intrinsic-procedures/tand.rst: New file.
* doc/gfortran/intrinsic-procedures/tanh.rst: New file.
* doc/gfortran/intrinsic-procedures/thisimage.rst: New file.
* doc/gfortran/intrinsic-procedures/time.rst: New file.
* doc/gfortran/intrinsic-procedures/time8.rst: New file.
* doc/gfortran/intrinsic-procedures/tiny.rst: New file.
* doc/gfortran/intrinsic-procedures/trailz.rst: New file.
* doc/gfortran/intrinsic-procedures/transfer.rst: New file.
* doc/gfortran/intrinsic-procedures/transpose.rst: New file.
* doc/gfortran/intrinsic-procedures/trim.rst: New file.
* doc/gfortran/intrinsic-procedures/ttynam.rst: New file.
* doc/gfortran/intrinsic-procedures/ubound.rst: New file.
* doc/gfortran/intrinsic-procedures/ucobound.rst: New file.
* doc/gfortran/intrinsic-procedures/umask.rst: New file.
* doc/gfortran/intrinsic-procedures/unlink.rst: New file.
* doc/gfortran/intrinsic-procedures/unpack.rst: New file.
* doc/gfortran/intrinsic-procedures/verify.rst: New file.
* doc/gfortran/intrinsic-procedures/xor.rst: New file.
* doc/gfortran/introduction.rst: New file.
* doc/gfortran/mixed-language-programming.rst: New file.
* doc/gfortran/naming-and-argument-passing-conventions.rst: New file.
* doc/gfortran/non-fortran-main-program.rst: New file.
* doc/gfortran/projects.rst: New file.
* doc/gfortran/runtime.rst: New file.
* doc/gfortran/runtime/gfortranconvertunit.rst: New file.
* doc/gfortran/runtime/gfortranerrorbacktrace.rst: New file.
* doc/gfortran/runtime/gfortranformattedbuffersize.rst: New file.
* doc/gfortran/runtime/gfortranlistseparator.rst: New file.
* doc/gfortran/runtime/gfortranoptionalplus.rst: New file.
* doc/gfortran/runtime/gfortranshowlocus.rst: New file.
* doc/gfortran/runtime/gfortranstderrunit.rst: New file.
* doc/gfortran/runtime/gfortranstdinunit.rst: New file.
* doc/gfortran/runtime/gfortranstdoutunit.rst: New file.
* doc/gfortran/runtime/gfortranunbufferedall.rst: New file.
* doc/gfortran/runtime/gfortranunbufferedpreconnected.rst: New file.
* doc/gfortran/runtime/gfortranunformattedbuffersize.rst: New file.
* doc/gfortran/runtime/tmpdir.rst: New file.
* doc/gfortran/standards.rst: New file.
* doc/gfortran/type-and-enum-abi-documentation.rst: New file.
gcc/go/ChangeLog:
* doc/c-interoperability.rst: New file.
* doc/c-type-interoperability.rst: New file.
* doc/compiler-directives.rst: New file.
* doc/conf.py: New file.
* doc/copyright.rst: New file.
* doc/function-names.rst: New file.
* doc/general-public-license-3.rst: New file.
* doc/gnu-free-documentation-license.rst: New file.
* doc/import-and-export.rst: New file.
* doc/index.rst: New file.
* doc/indices-and-tables.rst: New file.
* doc/introduction.rst: New file.
* doc/invoking-gccgo.rst: New file.
libgomp/ChangeLog:
* doc/amd-radeon-gcn.rst: New file.
* doc/conf.py: New file.
* doc/copyright.rst: New file.
* doc/cuda-streams-usage.rst: New file.
* doc/enabling-openacc.rst: New file.
* doc/enabling-openmp.rst: New file.
* doc/first-invocation-nvidia-cublas-library-api.rst: New file.
* doc/first-invocation-openacc-library-api.rst: New file.
* doc/funding.rst: New file.
* doc/general-public-license-3.rst: New file.
* doc/gnu-free-documentation-license.rst: New file.
* doc/implementation-status-and-implementation-defined-behavior.rst: New file.
* doc/index.rst: New file.
* doc/indices-and-tables.rst: New file.
* doc/introduction.rst: New file.
* doc/memory-allocation-with-libmemkind.rst: New file.
* doc/nvptx.rst: New file.
* doc/offload-target-specifics.rst: New file.
* doc/openacc-environment-variables.rst: New file.
* doc/openacc-environment-variables/accdevicenum.rst: New file.
* doc/openacc-environment-variables/accdevicetype.rst: New file.
* doc/openacc-environment-variables/accproflib.rst: New file.
* doc/openacc-environment-variables/gccaccnotify.rst: New file.
* doc/openacc-introduction.rst: New file.
* doc/openacc-library-and-environment-variables.rst: New file.
* doc/openacc-library-interoperability.rst: New file.
* doc/openacc-profiling-interface.rst: New file.
* doc/openacc-runtime-library-routines.rst: New file.
* doc/openacc-runtime-library-routines/accasynctest.rst: New file.
* doc/openacc-runtime-library-routines/accasynctestall.rst: New file.
* doc/openacc-runtime-library-routines/accattach.rst: New file.
* doc/openacc-runtime-library-routines/acccopyin.rst: New file.
* doc/openacc-runtime-library-routines/acccopyout.rst: New file.
* doc/openacc-runtime-library-routines/acccreate.rst: New file.
* doc/openacc-runtime-library-routines/accdelete.rst: New file.
* doc/openacc-runtime-library-routines/accdetach.rst: New file.
* doc/openacc-runtime-library-routines/accdeviceptr.rst: New file.
* doc/openacc-runtime-library-routines/accfree.rst: New file.
* doc/openacc-runtime-library-routines/accgetcudastream.rst: New file.
* doc/openacc-runtime-library-routines/accgetcurrentcudacontext.rst: New file.
* doc/openacc-runtime-library-routines/accgetcurrentcudadevice.rst: New file.
* doc/openacc-runtime-library-routines/accgetdevicenum.rst: New file.
* doc/openacc-runtime-library-routines/accgetdevicetype.rst: New file.
* doc/openacc-runtime-library-routines/accgetnumdevices.rst: New file.
* doc/openacc-runtime-library-routines/accgetproperty.rst: New file.
* doc/openacc-runtime-library-routines/acchostptr.rst: New file.
* doc/openacc-runtime-library-routines/accinit.rst: New file.
* doc/openacc-runtime-library-routines/accispresent.rst: New file.
* doc/openacc-runtime-library-routines/accmalloc.rst: New file.
* doc/openacc-runtime-library-routines/accmapdata.rst: New file.
* doc/openacc-runtime-library-routines/accmemcpyfromdevice.rst: New file.
* doc/openacc-runtime-library-routines/accmemcpytodevice.rst: New file.
* doc/openacc-runtime-library-routines/accondevice.rst: New file.
* doc/openacc-runtime-library-routines/accpresentorcopyin.rst: New file.
* doc/openacc-runtime-library-routines/accpresentorcreate.rst: New file.
* doc/openacc-runtime-library-routines/accproflookup.rst: New file.
* doc/openacc-runtime-library-routines/accprofregister.rst: New file.
* doc/openacc-runtime-library-routines/accprofunregister.rst: New file.
* doc/openacc-runtime-library-routines/accregisterlibrary.rst: New file.
* doc/openacc-runtime-library-routines/accsetcudastream.rst: New file.
* doc/openacc-runtime-library-routines/accsetdevicenum.rst: New file.
* doc/openacc-runtime-library-routines/accsetdevicetype.rst: New file.
* doc/openacc-runtime-library-routines/accshutdown.rst: New file.
* doc/openacc-runtime-library-routines/accunmapdata.rst: New file.
* doc/openacc-runtime-library-routines/accupdatedevice.rst: New file.
* doc/openacc-runtime-library-routines/accupdateself.rst: New file.
* doc/openacc-runtime-library-routines/accwait.rst: New file.
* doc/openacc-runtime-library-routines/accwaitall.rst: New file.
* doc/openacc-runtime-library-routines/accwaitallasync.rst: New file.
* doc/openacc-runtime-library-routines/accwaitasync.rst: New file.
* doc/openmp-context-selectors.rst: New file.
* doc/openmp-environment-variables.rst: New file.
* doc/openmp-environment-variables/gompcpuaffinity.rst: New file.
* doc/openmp-environment-variables/gompdebug.rst: New file.
* doc/openmp-environment-variables/gomprtemsthreadpools.rst: New file.
* doc/openmp-environment-variables/gompspincount.rst: New file.
* doc/openmp-environment-variables/gompstacksize.rst: New file.
* doc/openmp-environment-variables/ompcancellation.rst: New file.
* doc/openmp-environment-variables/ompdefaultdevice.rst: New file.
* doc/openmp-environment-variables/ompdisplayenv.rst: New file.
* doc/openmp-environment-variables/ompdynamic.rst: New file.
* doc/openmp-environment-variables/ompmaxactivelevels.rst: New file.
* doc/openmp-environment-variables/ompmaxtaskpriority.rst: New file.
* doc/openmp-environment-variables/ompnested.rst: New file.
* doc/openmp-environment-variables/ompnumteams.rst: New file.
* doc/openmp-environment-variables/ompnumthreads.rst: New file.
* doc/openmp-environment-variables/ompplaces.rst: New file.
* doc/openmp-environment-variables/ompprocbind.rst: New file.
* doc/openmp-environment-variables/ompschedule.rst: New file.
* doc/openmp-environment-variables/ompstacksize.rst: New file.
* doc/openmp-environment-variables/omptargetoffload.rst: New file.
* doc/openmp-environment-variables/ompteamsthreadlimit.rst: New file.
* doc/openmp-environment-variables/ompthreadlimit.rst: New file.
* doc/openmp-environment-variables/ompwaitpolicy.rst: New file.
* doc/openmp-implementation-specifics.rst: New file.
* doc/openmp-implementation-status.rst: New file.
* doc/openmp-implementation-status/openmp-45.rst: New file.
* doc/openmp-implementation-status/openmp-50.rst: New file.
* doc/openmp-implementation-status/openmp-51.rst: New file.
* doc/openmp-implementation-status/openmp-52.rst: New file.
* doc/openmp-runtime-library-routines.rst: New file.
* doc/openmp-runtime-library-routines/ompdestroylock.rst: New file.
* doc/openmp-runtime-library-routines/ompdestroynestlock.rst: New file.
* doc/openmp-runtime-library-routines/ompfulfillevent.rst: New file.
* doc/openmp-runtime-library-routines/ompgetactivelevel.rst: New file.
* doc/openmp-runtime-library-routines/ompgetancestorthreadnum.rst: New file.
* doc/openmp-runtime-library-routines/ompgetcancellation.rst: New file.
* doc/openmp-runtime-library-routines/ompgetdefaultdevice.rst: New file.
* doc/openmp-runtime-library-routines/ompgetdevicenum.rst: New file.
* doc/openmp-runtime-library-routines/ompgetdynamic.rst: New file.
* doc/openmp-runtime-library-routines/ompgetinitialdevice.rst: New file.
* doc/openmp-runtime-library-routines/ompgetlevel.rst: New file.
* doc/openmp-runtime-library-routines/ompgetmaxactivelevels.rst: New file.
* doc/openmp-runtime-library-routines/ompgetmaxtaskpriority.rst: New file.
* doc/openmp-runtime-library-routines/ompgetmaxteams.rst: New file.
* doc/openmp-runtime-library-routines/ompgetmaxthreads.rst: New file.
* doc/openmp-runtime-library-routines/ompgetnested.rst: New file.
* doc/openmp-runtime-library-routines/ompgetnumdevices.rst: New file.
* doc/openmp-runtime-library-routines/ompgetnumprocs.rst: New file.
* doc/openmp-runtime-library-routines/ompgetnumteams.rst: New file.
* doc/openmp-runtime-library-routines/ompgetnumthreads.rst: New file.
* doc/openmp-runtime-library-routines/ompgetprocbind.rst: New file.
* doc/openmp-runtime-library-routines/ompgetschedule.rst: New file.
* doc/openmp-runtime-library-routines/ompgetsupportedactivelevels.rst: New file.
* doc/openmp-runtime-library-routines/ompgetteamnum.rst: New file.
* doc/openmp-runtime-library-routines/ompgetteamsize.rst: New file.
* doc/openmp-runtime-library-routines/ompgetteamsthreadlimit.rst: New file.
* doc/openmp-runtime-library-routines/ompgetthreadlimit.rst: New file.
* doc/openmp-runtime-library-routines/ompgetthreadnum.rst: New file.
* doc/openmp-runtime-library-routines/ompgetwtick.rst: New file.
* doc/openmp-runtime-library-routines/ompgetwtime.rst: New file.
* doc/openmp-runtime-library-routines/ompinfinal.rst: New file.
* doc/openmp-runtime-library-routines/ompinitlock.rst: New file.
* doc/openmp-runtime-library-routines/ompinitnestlock.rst: New file.
* doc/openmp-runtime-library-routines/ompinparallel.rst: New file.
* doc/openmp-runtime-library-routines/ompisinitialdevice.rst: New file.
* doc/openmp-runtime-library-routines/ompsetdefaultdevice.rst: New file.
* doc/openmp-runtime-library-routines/ompsetdynamic.rst: New file.
* doc/openmp-runtime-library-routines/ompsetlock.rst: New file.
* doc/openmp-runtime-library-routines/ompsetmaxactivelevels.rst: New file.
* doc/openmp-runtime-library-routines/ompsetnested.rst: New file.
* doc/openmp-runtime-library-routines/ompsetnestlock.rst: New file.
* doc/openmp-runtime-library-routines/ompsetnumteams.rst: New file.
* doc/openmp-runtime-library-routines/ompsetnumthreads.rst: New file.
* doc/openmp-runtime-library-routines/ompsetschedule.rst: New file.
* doc/openmp-runtime-library-routines/ompsetteamsthreadlimit.rst: New file.
* doc/openmp-runtime-library-routines/omptestlock.rst: New file.
* doc/openmp-runtime-library-routines/omptestnestlock.rst: New file.
* doc/openmp-runtime-library-routines/ompunsetlock.rst: New file.
* doc/openmp-runtime-library-routines/ompunsetnestlock.rst: New file.
* doc/reporting-bugs.rst: New file.
* doc/the-libgomp-abi.rst: New file.
* doc/the-libgomp-abi/implementing-atomic-construct.rst: New file.
* doc/the-libgomp-abi/implementing-barrier-construct.rst: New file.
* doc/the-libgomp-abi/implementing-critical-construct.rst: New file.
* doc/the-libgomp-abi/implementing-firstprivate-lastprivate-copyin-and-copyprivate-clauses.rst:
New file.
* doc/the-libgomp-abi/implementing-flush-construct.rst: New file.
* doc/the-libgomp-abi/implementing-for-construct.rst: New file.
* doc/the-libgomp-abi/implementing-master-construct.rst: New file.
* doc/the-libgomp-abi/implementing-openaccs-parallel-construct.rst: New file.
* doc/the-libgomp-abi/implementing-ordered-construct.rst: New file.
* doc/the-libgomp-abi/implementing-parallel-construct.rst: New file.
* doc/the-libgomp-abi/implementing-private-clause.rst: New file.
* doc/the-libgomp-abi/implementing-reduction-clause.rst: New file.
* doc/the-libgomp-abi/implementing-sections-construct.rst: New file.
* doc/the-libgomp-abi/implementing-single-construct.rst: New file.
* doc/the-libgomp-abi/implementing-threadprivate-construct.rst: New file.
libiberty/ChangeLog:
* doc/bsd.rst: New file.
* doc/conf.py: New file.
* doc/copyright.rst: New file.
* doc/extensions.rst: New file.
* doc/function-variable-and-macro-listing.rst: New file.
* doc/index.rst: New file.
* doc/indices-and-tables.rst: New file.
* doc/introduction.rst: New file.
* doc/lesser-general-public-license-2.1.rst: New file.
* doc/overview.rst: New file.
* doc/replacement-functions.rst: New file.
* doc/supplemental-functions.rst: New file.
* doc/using.rst: New file.
libitm/ChangeLog:
* doc/c-c++-language-constructs-for-tm.rst: New file.
* doc/conf.py: New file.
* doc/copyright.rst: New file.
* doc/enabling-libitm.rst: New file.
* doc/gnu-free-documentation-license.rst: New file.
* doc/index.rst: New file.
* doc/indices-and-tables.rst: New file.
* doc/internals.rst: New file.
* doc/locking-conventions.rst: New file.
* doc/nesting-flat-vs-closed.rst: New file.
* doc/the-libitm-abi.rst: New file.
* doc/the-libitm-abi/function-list.rst: New file.
* doc/the-libitm-abi/future-enhancements-to-the-abi.rst: New file.
* doc/the-libitm-abi/library-design-principles.rst: New file.
* doc/the-libitm-abi/memory-model.rst: New file.
* doc/the-libitm-abi/non-objectives.rst: New file.
* doc/the-libitm-abi/objectives.rst: New file.
* doc/the-libitm-abi/sample-code.rst: New file.
* doc/the-libitm-abi/types-and-macros-list.rst: New file.
* doc/tm-methods-and-method-groups.rst: New file.
libquadmath/ChangeLog:
* doc/conf.py: New file.
* doc/copyright.rst: New file.
* doc/gnu-free-documentation-license.rst: New file.
* doc/i-o-library-routines.rst: New file.
* doc/index.rst: New file.
* doc/indices-and-tables.rst: New file.
* doc/introduction.rst: New file.
* doc/math-library-routines.rst: New file.
* doc/quadmathsnprintf.rst: New file.
* doc/reporting-bugs.rst: New file.
* doc/strtoflt128.rst: New file.
* doc/typedef-and-constants.rst: New file.
Diffstat (limited to 'gcc/fortran')
375 files changed, 26484 insertions, 0 deletions
diff --git a/gcc/fortran/doc/gfc-internals/code-that-interacts-with-the-user.rst b/gcc/fortran/doc/gfc-internals/code-that-interacts-with-the-user.rst new file mode 100644 index 0000000..43a47db --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/code-that-interacts-with-the-user.rst @@ -0,0 +1,15 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _user-interface: + +Code that Interacts with the User +--------------------------------- + +.. toctree:: + :maxdepth: 2 + + command-line-options + error-handling
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/command-line-options.rst b/gcc/fortran/doc/gfc-internals/command-line-options.rst new file mode 100644 index 0000000..abb5fda --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/command-line-options.rst @@ -0,0 +1,30 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _command-line-options: + +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 :samp:`lang.opt`, according +to the documentation in :ref:`gccint:options`. 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 ``gfc_handle_option`` code in +:samp:`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, ``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 +``gfc_option_t`` struct, which is defined in :samp:`gfortran.h`. +Before the options are processed, initial values for these flags are set +in ``gfc_init_option`` in :samp:`options.cc`; these become the default +values for the options.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/conf.py b/gcc/fortran/doc/gfc-internals/conf.py new file mode 100644 index 0000000..176e631 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/conf.py @@ -0,0 +1,24 @@ +# Configuration file for the Sphinx documentation builder. + +import sys +sys.path.append('../../../..//doc') + +from baseconf import * + +name = 'gfc-internals' +project = 'GNU Fortran Internals' +copyright = '2007-2022 Free Software Foundation, Inc.' +authors = 'The gfortran team' + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +latex_documents = [ + ('index', f'{name}.tex', project, authors, 'manual'), +] + +texinfo_documents = [ + ('index', name, project, authors, None, None, None, True) +] + +set_common(name, globals())
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/copyright.rst b/gcc/fortran/doc/gfc-internals/copyright.rst new file mode 100644 index 0000000..c778eb1 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/copyright.rst @@ -0,0 +1,25 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the GPL license file + +Copyright +^^^^^^^^^ + +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 +in the :ref:`gnu_fdl`. + +(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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/error-handling.rst b/gcc/fortran/doc/gfc-internals/error-handling.rst new file mode 100644 index 0000000..11c12b6 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/error-handling.rst @@ -0,0 +1,75 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _error-handling: + +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: + +.. code-block:: c++ + + IF = 3 + +Hypothetically, this may get passed to the matcher for an ``IF`` +statement. Since this could plausibly be an erroneous ``IF`` +statement, the matcher will buffer an error message reporting the +absence of an expected :samp:`(` following an ``IF``. Since no +matchers reported an error-free match, however, the parser will also try +matching this against a variable assignment. When ``IF`` is a valid +variable, this will be parsed as an assignment statement, and the error +discarded. However, when ``IF`` is not a valid variable, this +buffered error message will be reported to the user. + +The error handling code is implemented in :samp:`error.cc`. Errors are +normally entered into the buffer with the ``gfc_error`` function. +Warnings go through a similar buffering process, and are entered into +the buffer with ``gfc_warning``. There is also a special-purpose +function, ``gfc_notify_std``, for things which have an error/warning +status that depends on the currently-selected language standard. + +The ``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 ``gfc_error_flag_test`` function can be +used. The ``gfc_clear_error`` function will clear out any errors in +the buffer, without reporting them. The ``gfc_warning_check`` and +``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 ``gfc_push_error``, ``gfc_pop_error``, +and ``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 ``gfc_error_now`` and +``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 ``gfc_fatal_error`` +function should be used instead. For errors that are always the result +of a bug somewhere in the compiler, the ``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 ``printf`` +syntax, with :samp:`%`-escapes to insert variable values. The details, +and the allowable codes, are documented in the ``error_print`` +function in :samp:`error.cc`.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/frontend-data-structures.rst b/gcc/fortran/doc/gfc-internals/frontend-data-structures.rst new file mode 100644 index 0000000..0b4411a --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/frontend-data-structures.rst @@ -0,0 +1,23 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: data structures + +.. _frontend-data-structures: + +Frontend Data Structures +------------------------ + +This chapter should describe the details necessary to understand how +the various ``gfc_*`` data are used and interact. In general it is +advisable to read the code in :samp:`dump-parse-tree.cc` as its routines +should exhaust all possible valid combinations of content for these +structures. + +.. toctree:: + :maxdepth: 2 + + gfccode + gfcexpr
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages.rst b/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages.rst new file mode 100644 index 0000000..37bfe30 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages.rst @@ -0,0 +1,24 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _translating-to-generic: + +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 +:samp:`trans*.h` and :samp:`trans-*.c`. + +.. toctree:: + :maxdepth: 2 + + generating-the-intermediate-language-for-later-stages/basic-data-structures + generating-the-intermediate-language-for-later-stages/converting-expressions-to-tree + generating-the-intermediate-language-for-later-stages/translating-statements + generating-the-intermediate-language-for-later-stages/accessing-declarations
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/accessing-declarations.rst b/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/accessing-declarations.rst new file mode 100644 index 0000000..0c2c016 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/accessing-declarations.rst @@ -0,0 +1,16 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _accessing-declarations: + +Accessing declarations +********************** + +``gfc_symbol``, ``gfc_charlen`` and other front-end structures +contain a ``backend_decl`` variable, which contains the ``tree`` +used for accessing that entity in the middle-end. + +Accessing declarations is usually done by functions called +``gfc_get*``.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/basic-data-structures.rst b/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/basic-data-structures.rst new file mode 100644 index 0000000..2c564da --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/basic-data-structures.rst @@ -0,0 +1,67 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _basic-data-structures: + +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 ``tree``. Everything in +GENERIC is a ``tree``, including types and statements. Fortunately +for the gfortran programmer, ``tree`` variables are +garbage-collected, so doing memory management for them is not +necessary. + +``tree`` expressions are built using functions such as, for +example, ``fold_build2_loc``. For two tree variables ``a`` and +``b``, both of which have the type ``gfc_arry_index_type``, +calculation ``c = a * b`` would be done by + +.. code-block:: c++ + + c = fold_build2_loc (input_location, MULT_EXPR, + gfc_array_index_type, a, b); + +The types have to agree, otherwise internal compiler errors will occur +at a later stage. Expressions can be converted to a different type +using ``fold_convert``. + +Accessing individual members in the ``tree`` structures should not +be done. Rather, access should be done via macros. + +One basic data structure is the ``stmtblock_t`` struct. This is +used for holding a list of statements, expressed as ``tree`` +expressions. If a block is created using ``gfc_start_block``, it +has its own scope for variables; if it is created using +``gfc_init_block``, it does not have its own scope. + +It is possible to + +* Add an expression to the end of a block using ``gfc_add_expr_to_block`` + +* Add an expression to the beginning of a block using ``void gfc_prepend_expr_to_block`` + +* Make a block into a single ``tree`` using + ``gfc_finish_block``. For example, this is needed to put the + contents of a block into the ``if`` or ``else`` branch of + a ``COND_EXPR``. + +Variables are also ``tree`` expressions, they can be created using +``gfc_create_var``. Assigning to a variable can be done with +``gfc_add_modify``. + +An example: Creating a default integer type variable in the current +scope with the prefix 'everything' in the ``stmt_block`` +``block`` and assigning the value 42 would be + +.. code-block:: c++ + + 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));
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/converting-expressions-to-tree.rst b/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/converting-expressions-to-tree.rst new file mode 100644 index 0000000..f683804 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/converting-expressions-to-tree.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _converting-expressions: + +Converting Expressions to tree +****************************** + +Converting expressions to ``tree`` is done by functions called +``gfc_conv_*``. + +The central data structure for a GENERIC expression is the +``gfc_se`` structure. Its ``expr`` member is a ``tree`` that +holds the value of the expression. A ``gfc_se`` structure is +initialized using ``gfc_init_se`` ; it needs to be embedded in an +outer ``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, ``gfc_se`` contains the members ``pre`` and +``post``, which point to ``stmt_block`` blocks for code that +needs to be executed before and after evaluation of the expression. + +When using a local ``gfc_se`` to convert some expression, it is +often necessary to add the generated ``pre`` and ``post`` blocks +to the ``pre`` or ``post`` blocks of the outer ``gfc_se``. +Code like this (lifted from :samp:`trans-expr.cc`) is fairly common: + +.. code-block:: c++ + + 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); + +Conversion functions which need a ``gfc_se`` structure will have a +corresponding argument. + +``gfc_se`` also contains pointers to a ``gfc_ss`` and a +``gfc_loopinfo`` structure. These are needed by the scalarizer.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/translating-statements.rst b/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/translating-statements.rst new file mode 100644 index 0000000..f53310e --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/generating-the-intermediate-language-for-later-stages/translating-statements.rst @@ -0,0 +1,14 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _translating-statements: + +Translating statements +********************** + +Translating statements to ``tree`` is done by functions called +``gfc_trans_*``. These functions usually get passed a +``gfc_code`` structure, evaluate any expressions and then +return a ``tree`` structure.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/gfccode.rst b/gcc/fortran/doc/gfc-internals/gfccode.rst new file mode 100644 index 0000000..838205d --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/gfccode.rst @@ -0,0 +1,146 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: statement chaining + +.. _gfc_code: + +gfc_code +******** + +.. index:: gfc_code, struct gfc_code + +The executable statements in a program unit are represented by a +nested chain of ``gfc_code`` structures. The type of statement is +identified by the ``op`` member of the structure, the different +possible values are enumerated in ``gfc_exec_op``. A special +member of this ``enum`` is ``EXEC_NOP`` which is used to +represent the various ``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 ``next`` +and ``here`` fields. The former points to the next statement in +the current block or is ``NULL`` if the current statement is the +last in a block, ``here`` points to the statement label of the +current statement. + +If the current statement is one of ``IF``, ``DO``, ``SELECT`` +it starts a block, i.e. a nested level in the program. In order to +represent this, the ``block`` member is set to point to a +``gfc_code`` structure whose ``next`` member starts the chain of +statements inside the block; this structure's ``op`` member should be set to +the same value as the parent structure's ``op`` member. The ``SELECT`` +and ``IF`` statements may contain various blocks (the chain of ``ELSE IF`` +and ``ELSE`` blocks or the various ``CASE`` s, respectively). These chains +are linked-lists formed by the ``block`` members. + +Consider the following example code: + +.. code-block:: fortran + + IF (foo < 20) THEN + PRINT *, "Too small" + foo = 20 + ELSEIF (foo > 50) THEN + PRINT *, "Too large" + foo = 50 + ELSE + PRINT *, "Good" + END IF + +This statement-block will be represented in the internal gfortran tree as +follows, were the horizontal link-chains are those induced by the ``next`` +members and vertical links down are those of ``block``. :samp:`==|` and +:samp:`--|` mean ``NULL`` pointers to mark the end of a chain: + +.. code-block:: c++ + + ... ==> IF ==> ... + | + +--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==| + | + +--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==| + | + +--> ELSE ==> PRINT *, "Good" ==| + | + +--| + +IF Blocks +^^^^^^^^^ + +Conditionals are represented by ``gfc_code`` structures with their +``op`` member set to ``EXEC_IF``. This structure's ``block`` +member must point to another ``gfc_code`` node that is the header of the +if-block. This header's ``op`` member must be set to ``EXEC_IF``, too, +its ``expr`` member holds the condition to check for, and its ``next`` +should point to the code-chain of the statements to execute if the condition is +true. + +If in addition an ``ELSEIF`` or ``ELSE`` block is present, the +``block`` member of the if-block-header node points to yet another +``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 +``ELSE`` block without a new condition the ``expr`` member should be +``NULL``. This block can itself have its ``block`` member point to the +next ``ELSEIF`` or ``ELSE`` block if there's a chain of them. + +Loops +^^^^^ + +``DO`` loops are stored in the tree as ``gfc_code`` nodes with their +``op`` set to ``EXEC_DO`` for a ``DO`` loop with iterator variable and +to ``EXEC_DO_WHILE`` for infinite ``DO`` s and ``DO WHILE`` blocks. +Their ``block`` member should point to a ``gfc_code`` structure heading +the code-chain of the loop body; its ``op`` member should be set to +``EXEC_DO`` or ``EXEC_DO_WHILE``, too, respectively. + +For ``DO WHILE`` loops, the loop condition is stored on the top +``gfc_code`` structure's ``expr`` member; ``DO`` forever loops are +simply ``DO WHILE`` loops with a constant ``.TRUE.`` loop condition in +the internal representation. + +Similarly, ``DO`` loops with an iterator have instead of the condition their +``ext.iterator`` member set to the correct values for the loop iterator +variable and its range. + +SELECT Statements +^^^^^^^^^^^^^^^^^ + +A ``SELECT`` block is introduced by a ``gfc_code`` structure with an +``op`` member of ``EXEC_SELECT`` and ``expr`` containing the expression +to evaluate and test. Its ``block`` member starts a list of ``gfc_code`` +structures linked together by their ``block`` members that stores the various +``CASE`` parts. + +Each ``CASE`` node has its ``op`` member set to ``EXEC_SELECT``, too, +its ``next`` member points to the code-chain to be executed in the current +case-block, and ``extx.case_list`` contains the case-values this block +corresponds to. The ``block`` member links to the next case in the list. + +BLOCK and ASSOCIATE +^^^^^^^^^^^^^^^^^^^ + +The code related to a ``BLOCK`` statement is stored inside an +``gfc_code`` structure (say :samp:`{c}`) +with ``c.op`` set to ``EXEC_BLOCK``. The +``gfc_namespace`` holding the locally defined variables of the +``BLOCK`` is stored in ``c.ext.block.ns``. The code inside the +construct is in ``c.code``. + +``ASSOCIATE`` constructs are based on ``BLOCK`` and thus also have +the internal storage structure described above (including ``EXEC_BLOCK``). +However, for them ``c.ext.block.assoc`` is set additionally and points +to a linked list of ``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 ``BLOCK`` 's +namespace as ordinary symbols, but they have their ``gfc_symbol`` 's +member ``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 ``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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/gfcexpr.rst b/gcc/fortran/doc/gfc-internals/gfcexpr.rst new file mode 100644 index 0000000..7036ee4 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/gfcexpr.rst @@ -0,0 +1,156 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfc_expr: + +gfc_expr +******** + +.. index:: gfc_expr, 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 +``gfc_expr`` objects. The member ``expr_type`` specifies the overall +type of an expression (for instance, ``EXPR_CONSTANT`` for constants or +``EXPR_VARIABLE`` for variable references). The members ``ts`` and +``rank`` as well as ``shape``, which can be ``NULL``, specify +the type, rank and, if applicable, shape of the whole expression or expression +tree of which the current structure is the root. ``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 ``expr_type`` member), the corresponding structure +in the ``value`` union will usually contain additional data describing the +expression's value in a type-specific manner. The ``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. + +Constants +^^^^^^^^^ + +Scalar constants are represented by ``gfc_expr`` nodes with their +``expr_type`` set to ``EXPR_CONSTANT``. The constant's value shall +already be known at compile-time and is stored in the ``logical``, +``integer``, ``real``, ``complex`` or ``character`` struct inside +``value``, depending on the constant's type specification. + +Operators +^^^^^^^^^ + +Operator-expressions are expressions that are the result of the execution of +some operator on one or two operands. The expressions have an ``expr_type`` +of ``EXPR_OP``. Their ``value.op`` structure contains additional data. + +``op1`` and optionally ``op2`` if the operator is binary point to the +two operands, and ``operator`` or ``uop`` describe the operator that +should be evaluated on these operands, where ``uop`` describes a user-defined +operator. + +Function Calls +^^^^^^^^^^^^^^ + +If the expression is the return value of a function-call, its ``expr_type`` +is set to ``EXPR_FUNCTION``, and ``symtree`` must point to the symtree +identifying the function to be called. ``value.function.actual`` holds the +actual arguments given to the function as a linked list of +``gfc_actual_arglist`` nodes. + +The other members of ``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 ``symtree`` member. + +A special case of function calls are 'component calls' to type-bound +procedures; those have the ``expr_type`` ``EXPR_COMPCALL`` with +``value.compcall`` containing the argument list and the procedure called, +while ``symtree`` and ``ref`` describe the object on which the procedure +was called in the same way as a ``EXPR_VARIABLE`` expression would. +See :ref:`type-bound-procedures`. + +Array- and Structure-Constructors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Array- and structure-constructors (one could probably call them 'array-' and +'derived-type constants') are ``gfc_expr`` structures with their +``expr_type`` member set to ``EXPR_ARRAY`` or ``EXPR_STRUCTURE``, +respectively. For structure constructors, ``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 ``gfc_constructor`` nodes in the +``value.constructor`` member. + +Null +^^^^ + +``NULL`` is a special value for pointers; it can be of different base types. +Such a ``NULL`` value is represented in the internal tree by a +``gfc_expr`` node with ``expr_type`` ``EXPR_NULL``. If the base type +of the ``NULL`` expression is known, it is stored in ``ts`` (that's for +instance the case for default-initializers of ``ALLOCATABLE`` components), +but this member can also be set to ``BT_UNKNOWN`` if the information is not +available (for instance, when the expression is a pointer-initializer +``NULL()``). + +Variables and Reference Expressions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Variable references are ``gfc_expr`` structures with their ``expr_type`` +set to ``EXPR_VARIABLE`` ; their ``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 ``component`` is either an array or +a ``CHARACTER`` member of ``struct`` that is of some derived-type. Such a +chain of references is achieved by a linked list headed by ``ref`` of the +``gfc_expr`` node. For the example above it would be (:samp:`==|` is the +last ``NULL`` pointer): + +.. code-block:: c++ + + EXPR_VARIABLE(struct) ==> REF_COMPONENT(component) ==> REF_ARRAY(2:5) ==| + +If ``component`` is a string rather than an array, the last element would be +a ``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 +``REF_ARRAY`` reference must be built as the last element in the chain with +an array-reference type of ``AR_FULL``. Consider this example code: + +.. code-block:: fortran + + TYPE :: mytype + INTEGER :: array(42) + END TYPE mytype + + TYPE(mytype) :: variable + INTEGER :: local_array(5) + + CALL do_something (variable%array, local_array) + +The ``gfc_expr`` nodes representing the arguments to the :samp:`do_something` +call will have a reference-chain like this: + +.. code-block:: c++ + + EXPR_VARIABLE(variable) ==> REF_COMPONENT(array) ==> REF_ARRAY(FULL) ==| + EXPR_VARIABLE(local_array) ==> REF_ARRAY(FULL) ==| + +Constant Substring References +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``EXPR_SUBSTRING`` is a special type of expression that encodes a substring +reference of a constant string, as in the following code snippet: + +.. code-block:: c++ + + x = "abcde"(1:2) + +In this case, ``value.character`` contains the full string's data as if it +was a string constant, but the ``ref`` member is also set and points to a +substring reference as described in the subsection above.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/gnu-free-documentation-license.rst b/gcc/fortran/doc/gfc-internals/gnu-free-documentation-license.rst new file mode 100644 index 0000000..9a3dac6 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/gnu-free-documentation-license.rst @@ -0,0 +1,6 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. include:: ../../../../doc/gnu_free_documentation_license.rst
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/index.rst b/gcc/fortran/doc/gfc-internals/index.rst new file mode 100644 index 0000000..3e37acf --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/index.rst @@ -0,0 +1,24 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +GNU Fortran Compiler Internals +============================== + +.. only:: html + + Contents: + +.. toctree:: + + copyright + introduction + code-that-interacts-with-the-user + frontend-data-structures + internals-of-fortran-2003-oop-features + generating-the-intermediate-language-for-later-stages + the-libgfortran-runtime-library + gnu-free-documentation-license + + indices-and-tables
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/indices-and-tables.rst b/gcc/fortran/doc/gfc-internals/indices-and-tables.rst new file mode 100644 index 0000000..50865c6 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/indices-and-tables.rst @@ -0,0 +1 @@ +.. include:: ../../../../doc/indices-and-tables.rst
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/internals-of-fortran-2003-oop-features.rst b/gcc/fortran/doc/gfc-internals/internals-of-fortran-2003-oop-features.rst new file mode 100644 index 0000000..b57f60e --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/internals-of-fortran-2003-oop-features.rst @@ -0,0 +1,15 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _object-orientation: + +Internals of Fortran 2003 OOP Features +-------------------------------------- + +.. toctree:: + :maxdepth: 2 + + type-bound-procedures + type-bound-operators
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/introduction.rst b/gcc/fortran/doc/gfc-internals/introduction.rst new file mode 100644 index 0000000..cc13920 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/introduction.rst @@ -0,0 +1,32 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _introduction: + +Introduction +============ + +.. index:: Introduction + +This manual documents the internals of :command:`gfortran`, +the GNU Fortran compiler. + +.. only:: development + + .. 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. + +------------ + +.. The following duplicates the text on the TexInfo table of contents. + +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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/symbol-versioning.rst b/gcc/fortran/doc/gfc-internals/symbol-versioning.rst new file mode 100644 index 0000000..37bc1e7 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/symbol-versioning.rst @@ -0,0 +1,63 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _symbol-versioning: + +Symbol Versioning +***************** + +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: + +* `GNU ld manual <https://sourceware.org/binutils/docs/ld/VERSION.html>`_ + +* `ELF Symbol + Versioning - Ulrich Depper <https://www.akkadia.org/drepper/symbol-versioning>`_ + +* `How to Write Shared + Libraries - Ulrich Drepper (see Chapter 3) <https://www.akkadia.org/drepper/dsohowto.pdf>`_ + +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 ``foo`` and ``bar`` to +libgfortran for the next GCC release, the following should be added to +the map file: + +:: + + GFORTRAN_1.1 { + global: + foo; + bar; + } GFORTRAN_1.0; + +where ``GFORTRAN_1.0`` is the version node of the current release, +and ``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): + +.. code-block:: c++ + + __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"); + +In this example, ``foo@`` represents the symbol ``foo`` bound to +the unspecified base version of the symbol. The source file that +contains this example would define 4 C functions: ``original_foo``, +``old_foo``, ``old_foo1``, and ``new_foo``. + +In this case the map file must contain ``foo`` in ``VERS_1.1`` +and ``VERS_1.2`` as well as in ``VERS_2.0``.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/the-libgfortran-runtime-library.rst b/gcc/fortran/doc/gfc-internals/the-libgfortran-runtime-library.rst new file mode 100644 index 0000000..6b48b39 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/the-libgfortran-runtime-library.rst @@ -0,0 +1,14 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _libgfortran: + +The LibGFortran Runtime Library +------------------------------- + +.. toctree:: + :maxdepth: 2 + + symbol-versioning
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/type-bound-operators.rst b/gcc/fortran/doc/gfc-internals/type-bound-operators.rst new file mode 100644 index 0000000..395de8f --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/type-bound-operators.rst @@ -0,0 +1,33 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _type-bound-operators: + +Type-bound Operators +******************** + +Type-bound operators are in fact basically just ``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 ``.MYOPERATOR.``) +are stored in the ``f2k_derived`` namespace's ``tb_uop_root`` +symtree exactly like ordinary type-bound procedures are stored in +``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 ``tb_op`` indexed by the intrinsic operator's enum +value. Those need not be packed into ``gfc_symtree`` structures and are +only ``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 ``GENERIC`` +type-bound procedure call to the respective definition and that call is +further processed.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfc-internals/type-bound-procedures.rst b/gcc/fortran/doc/gfc-internals/type-bound-procedures.rst new file mode 100644 index 0000000..2f2d7c1 --- /dev/null +++ b/gcc/fortran/doc/gfc-internals/type-bound-procedures.rst @@ -0,0 +1,101 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _type-bound-procedures: + +Type-bound Procedures +********************* + +Type-bound procedures are stored in the ``tb_sym_root`` of the namespace +``f2k_derived`` associated with the derived-type symbol as ``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 ``n.tb`` a struct of type +``gfc_typebound_proc`` containing the additional data needed: The +binding attributes (like ``PASS`` and ``NOPASS``, ``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, ``overridden`` +points to this binding's ``gfc_typebound_proc`` structure. + +Specific Bindings +^^^^^^^^^^^^^^^^^ + +.. - + +For specific bindings (declared with ``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 ``pass_arg_num`` in ``gfc_typebound_proc``. +The binding's target procedure is pointed-to by ``u.specific``. + +``DEFERRED`` bindings are just like ordinary specific bindings, except +that their ``deferred`` flag is set of course and that ``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. + +Generic Bindings +^^^^^^^^^^^^^^^^ + +.. - + +Bindings declared as ``GENERIC`` store the specific bindings they target as +a linked list using nodes of type ``gfc_tbp_generic`` in ``u.generic``. +For each specific target, the parser records its symtree and during resolution +this symtree is bound to the corresponding ``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 (``value.compcall.tbp``) is re-pointed to +the found specific binding and this call is subsequently handled by the logic +for specific binding calls. + +Calls to Type-bound Procedures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. - + +Calls to type-bound procedures are stored in the parse-tree as ``gfc_expr`` +nodes of type ``EXPR_COMPCALL``. Their ``value.compcall.actual`` saves +the actual argument list of the call and ``value.compcall.tbp`` points to the +``gfc_typebound_proc`` structure of the binding to be called. The object +in whose context the procedure was called is saved by combination of +``symtree`` and ``ref``, as if the expression was of type +``EXPR_VARIABLE``. + +For code like this: + +.. code-block:: fortran + + CALL myobj%procedure (arg1, arg2) + +the ``CALL`` is represented in the parse-tree as a ``gfc_code`` node of +type ``EXEC_COMPCALL``. The ``expr`` member of this node holds an +expression of type ``EXPR_COMPCALL`` of the same structure as mentioned above +except that its target procedure is of course a ``SUBROUTINE`` and not a +``FUNCTION``. + +Expressions that are generated internally (as expansion of a type-bound +operator call) may also use additional flags and members. +``value.compcall.ignore_pass`` signals that even though a ``PASS`` +attribute may be present the actual argument list should not be updated because +it already contains the passed-object. +``value.compcall.base_object`` overrides, if it is set, the base-object +(that is normally stored in ``symtree`` and ``ref`` as mentioned above); +this is needed because type-bound operators can be called on a base-object that +need not be of type ``EXPR_VARIABLE`` and thus representable in this way. +Finally, if ``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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/about-gnu-fortran.rst b/gcc/fortran/doc/gfortran/about-gnu-fortran.rst new file mode 100644 index 0000000..8185248 --- /dev/null +++ b/gcc/fortran/doc/gfortran/about-gnu-fortran.rst @@ -0,0 +1,115 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _about-gnu-fortran: + +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 +`NIST Fortran 77 Test Suite <http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html>`_, and produces acceptable results on the +`LAPACK Test Suite <https://www.netlib.org/lapack/faq.html>`_. +It also provides respectable performance on +the `Polyhedron Fortran compiler benchmarks <https://polyhedron.com/?page_id=175>`_ and the +`Livermore Fortran Kernels test <https://www.netlib.org/benchmark/livermore>`_. It has been used to compile a number of +large real-world programs, including +`the HARMONIE and HIRLAM weather forecasting code <http://hirlam.org/>`_ and +`the Tonto quantum chemistry package <https://github.com/dylan-jayatilaka/tonto>`_; see +https://gcc.gnu.org/wiki/GfortranApps for an extended list. + +GNU Fortran provides the following functionality: + +* Read a program, stored in a file and containing :dfn:`source code` + instructions written in Fortran 77. + +* 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. + +* 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`. + +* 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. + +* 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`). + +* 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. + +The GNU Fortran compiler consists of several components: + +* 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. + +* 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. + +* 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. + + .. and mechanisms to spawn, + + .. unleash and pause threads in parallelized code. + +* 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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/coarray-programming.rst b/gcc/fortran/doc/gfortran/coarray-programming.rst new file mode 100644 index 0000000..4dce202 --- /dev/null +++ b/gcc/fortran/doc/gfortran/coarray-programming.rst @@ -0,0 +1,17 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: Coarrays + +.. _coarray-programming: + +Coarray Programming +------------------- + +.. toctree:: + :maxdepth: 2 + + type-and-enum-abi-documentation + function-abi-documentation
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics.rst b/gcc/fortran/doc/gfortran/compiler-characteristics.rst new file mode 100644 index 0000000..c222102 --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics.rst @@ -0,0 +1,27 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _compiler-characteristics: + +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. + +.. toctree:: + :maxdepth: 2 + + compiler-characteristics/kind-type-parameters + compiler-characteristics/internal-representation-of-logical-variables + compiler-characteristics/evaluation-of-logical-expressions + compiler-characteristics/max-and-min-intrinsics-with-real-nan-arguments + compiler-characteristics/thread-safety-of-the-runtime-library + compiler-characteristics/data-consistency-and-durability + compiler-characteristics/files-opened-without-an-explicit-action=-specifier + compiler-characteristics/file-operations-on-symbolic-links + compiler-characteristics/file-format-of-unformatted-sequential-files + compiler-characteristics/asynchronous-i-o
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics/asynchronous-i-o.rst b/gcc/fortran/doc/gfortran/compiler-characteristics/asynchronous-i-o.rst new file mode 100644 index 0000000..c5fd4ea --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics/asynchronous-i-o.rst @@ -0,0 +1,21 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: input/output, asynchronous, asynchronous I/O + +.. _asynchronous-i-o: + +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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics/data-consistency-and-durability.rst b/gcc/fortran/doc/gfortran/compiler-characteristics/data-consistency-and-durability.rst new file mode 100644 index 0000000..d499a8d --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics/data-consistency-and-durability.rst @@ -0,0 +1,80 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: consistency, durability + +.. _data-consistency-and-durability: + +Data consistency and 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 ``FNUM`` to retrieve the +low level file descriptor corresponding to an open Fortran unit. Then, +using e.g. the ``ISO_C_BINDING`` feature, one can call the +underlying system call to flush dirty data to stable storage, such as +``fsync`` on POSIX, ``_commit`` on MingW, or ``fcntl(fd, +F_FULLSYNC, 0)`` on Mac OS X. The following example shows how to call +fsync: + +.. code-block:: fortran + + ! 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" + +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 +``FLUSH`` statement. Also, the buffering can be turned off with the +``GFORTRAN_UNBUFFERED_ALL`` and +``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 ``dir`` command can show a stale size for a +file. One can force a directory metadata update by closing the unit, +or by calling ``_commit`` on the file descriptor. Note, though, +that ``_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. ``fsync`` will also force a flush of dirty data and metadata +to the server. Similar to ``open`` and ``close``, acquiring and +releasing ``fcntl`` file locks, if the server supports them, will +also force cache validation and flushing dirty data and metadata.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics/evaluation-of-logical-expressions.rst b/gcc/fortran/doc/gfortran/compiler-characteristics/evaluation-of-logical-expressions.rst new file mode 100644 index 0000000..ddb472b --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics/evaluation-of-logical-expressions.rst @@ -0,0 +1,18 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _evaluation-of-logical-expressions: + +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 ``.AND.`` or ``.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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics/file-format-of-unformatted-sequential-files.rst b/gcc/fortran/doc/gfortran/compiler-characteristics/file-format-of-unformatted-sequential-files.rst new file mode 100644 index 0000000..55c332c --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics/file-format-of-unformatted-sequential-files.rst @@ -0,0 +1,63 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: file, unformatted sequential, unformatted sequential, sequential, unformatted, record marker, subrecord + +.. _file-format-of-unformatted-sequential-files: + +File format of unformatted sequential files +******************************************* + +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: + +.. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics/file-operations-on-symbolic-links.rst b/gcc/fortran/doc/gfortran/compiler-characteristics/file-operations-on-symbolic-links.rst new file mode 100644 index 0000000..c0d1e10 --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics/file-operations-on-symbolic-links.rst @@ -0,0 +1,28 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: file, symbolic link + +.. _file-operations-on-symbolic-links: + +File operations on symbolic links +********************************* + +This section documents the behavior of GNU Fortran for file operations on +symbolic links, on systems that support them. + +* Results of INQUIRE statements of the 'inquire by file' form will + relate to the target of the symbolic link. For example, + ``INQUIRE(FILE="foo",EXIST=ex)`` will set :samp:`{ex}` to :samp:`{.true.}` if + :samp:`{foo}` is a symbolic link pointing to an existing file, and :samp:`{.false.}` + if :samp:`{foo}` points to an non-existing file ('dangling' symbolic link). + +* Using the ``OPEN`` statement with a ``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. + +* If a symbolic link was connected, using the ``CLOSE`` statement + with a ``STATUS="DELETE"`` specifier will cause the symbolic link itself + to be deleted, not its target.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics/files-opened-without-an-explicit-action=-specifier.rst b/gcc/fortran/doc/gfortran/compiler-characteristics/files-opened-without-an-explicit-action=-specifier.rst new file mode 100644 index 0000000..2f7a6dc --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics/files-opened-without-an-explicit-action=-specifier.rst @@ -0,0 +1,23 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: open, action + +.. _files-opened-without-an-explicit-action=-specifier: + +Files opened without an explicit ACTION= specifier +************************************************** + +The Fortran standard says that if an ``OPEN`` statement is executed +without an explicit ``ACTION=`` specifier, the default value is +processor dependent. GNU Fortran behaves as follows: + +* Attempt to open the file with ``ACTION='READWRITE'`` + +* If that fails, try to open with ``ACTION='READ'`` + +* If that fails, try to open with ``ACTION='WRITE'`` + +* If that fails, generate an error
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics/internal-representation-of-logical-variables.rst b/gcc/fortran/doc/gfortran/compiler-characteristics/internal-representation-of-logical-variables.rst new file mode 100644 index 0000000..2628065 --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics/internal-representation-of-logical-variables.rst @@ -0,0 +1,24 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: logical, variable representation + +.. _internal-representation-of-logical-variables: + +Internal representation of LOGICAL variables +******************************************** + +The Fortran standard does not specify how variables of ``LOGICAL`` +type are represented, beyond requiring that ``LOGICAL`` variables +of default kind have the same storage size as default ``INTEGER`` +and ``REAL`` variables. The GNU Fortran internal representation is +as follows. + +A ``LOGICAL(KIND=N)`` variable is represented as an +``INTEGER(KIND=N)`` variable, however, with only two permissible +values: ``1`` for ``.TRUE.`` and ``0`` for +``.FALSE.``. Any other integer value results in undefined behavior. + +See also :ref:`argument-passing-conventions` and :ref:`interoperability-with-c`.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics/kind-type-parameters.rst b/gcc/fortran/doc/gfortran/compiler-characteristics/kind-type-parameters.rst new file mode 100644 index 0000000..8f74c8d --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics/kind-type-parameters.rst @@ -0,0 +1,54 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: kind + +.. _kind-type-parameters: + +KIND Type Parameters +******************** + +The ``KIND`` type parameters supported by GNU Fortran for the primitive +data types are: + +``INTEGER`` + + 1, 2, 4, 8 [#f1]_, 16 [#f1]_, default: 4 [#f2]_ + +``LOGICAL`` + + 1, 2, 4, 8 [#f1]_, 16 [#f1]_, default: 4 [#f2]_ + +``REAL`` + + 4, 8, 10 [#f1]_, 16 [#f1]_, default: 4 [#f3]_ + +``COMPLEX`` + + 4, 8, 10 [#f1]_, 16 [#f1]_, default: 4 [#f3]_ + +``DOUBLE PRECISION`` + + 4, 8, 10 [#f1]_, 16 [#f1]_, default: 8 [#f3]_ + +``CHARACTER`` + + 1, 4, default: 1 + +.. [#f1] not available on all systems +.. [#f2] unless :option:`-fdefault-integer-8` is used +.. [#f3] unless :option:`-fdefault-real-8` is used (see :ref:`fortran-dialect-options`) + +The ``KIND`` value matches the storage size in bytes, except for +``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 ``INT8``, ``INT16``, +``INT32``, ``INT64``, ``REAL32``, ``REAL64``, and ``REAL128`` +parameters of the ``ISO_FORTRAN_ENV`` module instead of the concrete values. +The available kind parameters can be found in the constant arrays +``CHARACTER_KINDS``, ``INTEGER_KINDS``, ``LOGICAL_KINDS`` and +``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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics/max-and-min-intrinsics-with-real-nan-arguments.rst b/gcc/fortran/doc/gfortran/compiler-characteristics/max-and-min-intrinsics-with-real-nan-arguments.rst new file mode 100644 index 0000000..5b56829 --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics/max-and-min-intrinsics-with-real-nan-arguments.rst @@ -0,0 +1,21 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MAX, MIN, NaN + +.. _max-and-min-intrinsics-with-real-nan-arguments: + +MAX and MIN intrinsics with REAL NaN arguments +********************************************** + +The Fortran standard does not specify what the result of the +``MAX`` and ``MIN`` intrinsics are if one of the arguments is a +``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 ``NaN``, it is necessary to +explicitly test the arguments before calling ``MAX`` or ``MIN``, +e.g. with the ``IEEE_IS_NAN`` function from the intrinsic module +``IEEE_ARITHMETIC``.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/compiler-characteristics/thread-safety-of-the-runtime-library.rst b/gcc/fortran/doc/gfortran/compiler-characteristics/thread-safety-of-the-runtime-library.rst new file mode 100644 index 0000000..e2282ca --- /dev/null +++ b/gcc/fortran/doc/gfortran/compiler-characteristics/thread-safety-of-the-runtime-library.rst @@ -0,0 +1,53 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: thread-safety, threads + +.. _thread-safety-of-the-runtime-library: + +Thread-safety of the runtime library +************************************ + +GNU Fortran can be used in programs with multiple threads, e.g. by +using OpenMP, by calling OS thread handling functions via the +``ISO_C_BINDING`` facility, or by GNU Fortran compiled library code +being called from a multi-threaded program. + +The GNU Fortran runtime library, (``libgfortran``), supports being +called concurrently from multiple threads with the following +exceptions. + +During library initialization, the C ``getenv`` function is used, +which need not be thread-safe. Similarly, the ``getenv`` +function is used to implement the ``GET_ENVIRONMENT_VARIABLE`` and +``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 ``EXECUTE_COMMAND_LINE`` and ``SYSTEM`` intrinsics are +implemented with the ``system`` function, which need not be +thread-safe. It is the responsibility of the user to ensure that +``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 ``strtod`` and ``snprintf``. In +order to work correctly in locale-aware programs that set the locale +using ``setlocale``, the locale is reset to the default 'C' +locale while executing a formatted ``READ`` or ``WRITE`` +statement. On targets supporting the POSIX 2008 per-thread locale +functions (e.g. ``newlocale``, ``uselocale``, +``freelocale``), these are used and thus the global locale set +using ``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 ``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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/conf.py b/gcc/fortran/doc/gfortran/conf.py new file mode 100644 index 0000000..8be1e53 --- /dev/null +++ b/gcc/fortran/doc/gfortran/conf.py @@ -0,0 +1,30 @@ +# Configuration file for the Sphinx documentation builder. + +import sys +sys.path.append('../../../..//doc') + +from baseconf import * + +name = 'gfortran' +project = 'Using GNU Fortran' +copyright = '1999-2022 Free Software Foundation, Inc.' +authors = 'The gfortran team' + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +latex_documents = [ + ('index', f'{name}.tex', project, authors, 'manual'), +] + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('gnu-fortran-command-options', name, 'GNU Fortran compiler', [authors], 1), +] + +texinfo_documents = [ + ('index', name, project, authors, None, None, None, True) +] + +set_common(name, globals())
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/contributing.rst b/gcc/fortran/doc/gfortran/contributing.rst new file mode 100644 index 0000000..bb06b37 --- /dev/null +++ b/gcc/fortran/doc/gfortran/contributing.rst @@ -0,0 +1,28 @@ +.. _contributing: + +Contributing +============ + +.. index:: 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. + +.. toctree:: + :maxdepth: 2 + + contributors-to-gnu-fortran + projects
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/contributors-to-gnu-fortran.rst b/gcc/fortran/doc/gfortran/contributors-to-gnu-fortran.rst new file mode 100644 index 0000000..5a9c615 --- /dev/null +++ b/gcc/fortran/doc/gfortran/contributors-to-gnu-fortran.rst @@ -0,0 +1,109 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: Contributors, Credits, Authors + +.. _contributors: + +Contributors to GNU Fortran +*************************** + +Most of the parser was hand-crafted by *Andy Vaught*, who is +also the initiator of the whole project. Thanks Andy! +Most of the interface with GCC was written by *Paul Brook*. + +The following individuals have contributed code and/or +ideas and significant help to the GNU Fortran project +(in alphabetical order): + +* Janne Blomqvist + +* Steven Bosscher + +* Paul Brook + +* Tobias Burnus + +* François-Xavier Coudert + +* Bud Davis + +* Jerry DeLisle + +* Erik Edelmann + +* Bernhard Fischer + +* Daniel Franke + +* Richard Guenther + +* Richard Henderson + +* Katherine Holcomb + +* Jakub Jelinek + +* Niels Kristian Bech Jensen + +* Steven Johnson + +* Steven G. Kargl + +* Thomas Koenig + +* Asher Langton + +* H.J. Lu + +* Toon Moene + +* Brooks Moses + +* Andrew Pinski + +* Tim Prince + +* Christopher D. Rickett + +* Richard Sandiford + +* Tobias Schlüter + +* Roger Sayle + +* Paul Thomas + +* Andy Vaught + +* Feng Wang + +* Janus Weil + +* Daniel Kraft + +The following people have contributed bug reports, +smaller or larger patches, +and much needed feedback and encouragement for the +GNU Fortran project: + +* Bill Clodius + +* Dominique d'Humiēres + +* Kate Hedstrom + +* Erik Schnetter + +* Gerhard Steinmetz + +* Joost VandeVondele + +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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/copyright.rst b/gcc/fortran/doc/gfortran/copyright.rst new file mode 100644 index 0000000..c778eb1 --- /dev/null +++ b/gcc/fortran/doc/gfortran/copyright.rst @@ -0,0 +1,25 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the GPL license file + +Copyright +^^^^^^^^^ + +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 +in the :ref:`gnu_fdl`. + +(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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/extensions-implemented-in-gnu-fortran.rst b/gcc/fortran/doc/gfortran/extensions-implemented-in-gnu-fortran.rst new file mode 100644 index 0000000..bffdd27 --- /dev/null +++ b/gcc/fortran/doc/gfortran/extensions-implemented-in-gnu-fortran.rst @@ -0,0 +1,1535 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: extensions, implemented + +.. _extensions-implemented-in-gnu-fortran: + +Extensions implemented in GNU Fortran +************************************* + +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`. + +.. toctree:: + :maxdepth: 2 + + +.. index:: kind, old-style + +.. _old-style-kind-specifications: + +Old-style kind specifications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GNU Fortran allows old-style kind specifications in declarations. These +look like: + +.. code-block:: fortran + + TYPESPEC*size x,y,z + +where ``TYPESPEC`` is a basic type (``INTEGER``, ``REAL``, +etc.), and where ``size`` is a byte count corresponding to the +storage size of a valid kind for that type. (For ``COMPLEX`` +variables, ``size`` is the total size of the real and imaginary +parts.) The statement then declares ``x``, ``y`` and ``z`` to +be of type ``TYPESPEC`` with the appropriate kind. This is +equivalent to the standard-conforming declaration + +.. code-block:: fortran + + TYPESPEC(k) x,y,z + +where ``k`` is the kind parameter suitable for the intended precision. As +kind parameters are implementation-dependent, use the ``KIND``, +``SELECTED_INT_KIND`` and ``SELECTED_REAL_KIND`` intrinsics to retrieve +the correct value, for instance ``REAL*8 x`` can be replaced by: + +.. code-block:: fortran + + INTEGER, PARAMETER :: dbl = KIND(1.0d0) + REAL(KIND=dbl) :: x + +.. _old-style-variable-initialization: + +Old-style variable initialization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GNU Fortran allows old-style initialization of variables of the +form: + +.. code-block:: fortran + + INTEGER i/1/,j/2/ + REAL x(2,2) /3*0.,1./ + +The syntax for the initializers is as for the ``DATA`` statement, but +unlike in a ``DATA`` statement, an initializer only applies to the +variable immediately preceding the initialization. In other words, +something like ``INTEGER I,J/2,3/`` is not valid. This style of +initialization is only allowed in declarations without double colons +(``::``); 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: + +.. code-block:: fortran + + ! 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./ + +Note that variables which are explicitly initialized in declarations +or in ``DATA`` statements automatically acquire the ``SAVE`` +attribute. + +.. index:: Namelist + +.. _extensions-to-namelist: + +Extensions to 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:`&` + +.. code-block:: + + $MYNML + X(:)%Y(2) = 1.0 2.0 3.0 + CH(1:4) = "abcd" + $END + +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: + +.. code-block:: + + ? + + &mynml + x + x%y + ch + &end + +Entering :samp:`=?` outputs the namelist to stdout, as if +``WRITE(*,NML = mynml)`` had been called: + +.. code-block:: + + =? + + &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, / + +To aid this dialog, when input is from stdin, errors send their +messages to stderr and execution continues, even if ``IOSTAT`` is set. + +``PRINT`` namelist is permitted. This causes an error if +:option:`-std=f95` is used. + +.. code-block:: fortran + + PROGRAM test_print + REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/) + NAMELIST /mynml/ x + PRINT mynml + END PROGRAM test_print + +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. + +.. code-block:: fortran + + &MYNML + X(1,1) = 0.00 , 1.00 , 2.00 + / + +When writing a namelist, if no ``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. + +.. _x-format-descriptor-without-count-field: + +X format descriptor without count field +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To support legacy codes, GNU Fortran permits the count field of the +``X`` edit descriptor in ``FORMAT`` statements to be omitted. +When omitted, the count is implicitly assumed to be one. + +.. code-block:: fortran + + PRINT 10, 2, 3 + 10 FORMAT (I1, X, I1) + +.. _commas-in-format-specifications: + +Commas in FORMAT specifications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To support legacy codes, GNU Fortran allows the comma separator +to be omitted immediately before and after character string edit +descriptors in ``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. + +.. code-block:: fortran + + PRINT 10, 2, 3 + 10 FORMAT ('FOO='I1' BAR='I2) + print 20, 5, 6 + 20 FORMAT (I3, I3,) + +.. _missing-period-in-format-specifications: + +Missing period in 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. + +.. code-block:: fortran + + REAL :: value + READ(*,10) value + 10 FORMAT ('F4') + +.. _default-widths-for-f,-g-and-i-format-descriptors: + +Default widths for F, G and 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. + +.. code-block:: fortran + + REAL :: value1 + INTEGER :: value2 + WRITE(*,10) value1, value1, value2 + 10 FORMAT ('F, G, I') + +.. index:: I/O item lists + +.. _i-o-item-lists: + +I/O item lists +^^^^^^^^^^^^^^ + +To support legacy codes, GNU Fortran allows the input item list +of the ``READ`` statement, and the output item lists of the +``WRITE`` and ``PRINT`` statements, to start with a comma. + +.. index:: Q exponent-letter + +Q exponent-letter +^^^^^^^^^^^^^^^^^ + +GNU Fortran accepts real literal constants with an exponent-letter +of ``Q``, for example, ``1.23Q45``. The constant is interpreted +as a ``REAL(16)`` entity on targets that support this type. If +the target does not support ``REAL(16)`` but has a ``REAL(10)`` +type, then the real-literal-constant will be interpreted as a +``REAL(10)`` entity. In the absence of ``REAL(16)`` and +``REAL(10)``, an error will occur. + +.. index:: BOZ literal constants + +.. _boz-literal-constants: + +BOZ literal constants +^^^^^^^^^^^^^^^^^^^^^ + +Besides decimal constants, Fortran also supports binary (``b``), +octal (``o``) and hexadecimal (``z``) integer constants. The +syntax is: :samp:`prefix quote digits quote`, where the prefix is +either ``b``, ``o`` or ``z``, quote is either ``'`` or +``"`` and the digits are ``0`` or ``1`` for binary, +between ``0`` and ``7`` for octal, and between ``0`` and +``F`` for hexadecimal. (Example: ``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 ``REAL``, +``DBLE``, ``INT`` and ``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 ``X`` prefix. That the BOZ literal +constant can also be specified by adding a suffix to the string, for +example, ``Z'ABC'`` and ``'ABC'X`` are equivalent. Additionally, +as extension, BOZ literals are permitted in some contexts outside of +``DATA`` and the intrinsic functions listed in the Fortran standard. +Use :option:`-fallow-invalid-boz` to enable the extension. + +.. index:: array, indices of type real + +.. _real-array-indices: + +Real array indices +^^^^^^^^^^^^^^^^^^ + +As an extension, GNU Fortran allows the use of ``REAL`` expressions +or variables as array indices. + +.. index:: operators, unary + +.. _unary-operators: + +Unary operators +^^^^^^^^^^^^^^^ + +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. + +.. code-block:: fortran + + X = Y * -Z + +.. index:: conversion, to integer, conversion, to logical + +.. _implicitly-convert-logical-and-integer-values: + +Implicitly convert LOGICAL and INTEGER values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As an extension for backwards compatibility with other compilers, GNU +Fortran allows the implicit conversion of ``LOGICAL`` values to +``INTEGER`` values and vice versa. When converting from a +``LOGICAL`` to an ``INTEGER``, ``.FALSE.`` is interpreted as +zero, and ``.TRUE.`` is interpreted as one. When converting from +``INTEGER`` to ``LOGICAL``, the value zero is interpreted as +``.FALSE.`` and any nonzero value is interpreted as ``.TRUE.``. + +.. code-block:: fortran + + LOGICAL :: l + l = 1 + +.. code-block:: fortran + + INTEGER :: i + i = .TRUE. + +However, there is no implicit conversion of ``INTEGER`` values in +``if`` -statements, nor of ``LOGICAL`` or ``INTEGER`` values +in I/O operations. + +.. index:: Hollerith constants + +.. _hollerith-constants-support: + +Hollerith constants support +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GNU Fortran supports Hollerith constants in assignments, ``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 ``H`` or +``h``, and stored in bytewise fashion in a numeric (``INTEGER``, +``REAL``, or ``COMPLEX``), ``LOGICAL`` or ``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: + +.. code-block:: fortran + + complex*16 x(2) + data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/ + x(1) = 16HABCDEFGHIJKLMNOP + call foo (4h abc) + +Examples of Hollerith constants: + +.. code-block:: fortran + + 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. + +In general, Hollerith constants were used to provide a rudimentary +facility for handling character strings in early Fortran compilers, +prior to the introduction of ``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 ``TRANSFER`` statement, as in this example. + +.. code-block:: fortran + + integer(kind=4) :: a + a = transfer ("abcd", a) ! equivalent to: a = 4Habcd + +The use of the :option:`-fdec` option extends support of Hollerith constants +to comparisons: + +.. code-block:: fortran + + integer*4 a + a = 4hABCD + if (a .ne. 4habcd) then + write(*,*) "no match" + end if + +Supported types are numeric (``INTEGER``, ``REAL``, or ``COMPLEX``), +and ``CHARACTER``. + +.. index:: conversion, to character + +.. _character-conversion: + +Character conversion +^^^^^^^^^^^^^^^^^^^^ + +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 ``kind=1``. + +Character literals can be used in ``DATA`` statements and assignments with +numeric (``INTEGER``, ``REAL``, or ``COMPLEX``) or ``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: + +.. code-block:: fortran + + integer*4 x + data x / 'abcd' / + + x = 'A' ! Will be padded. + x = 'ab1234' ! Will be truncated. + +.. index:: pointer, Cray + +.. _cray-pointers: + +Cray pointers +^^^^^^^^^^^^^ + +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: + +.. code-block:: fortran + + pointer ( <pointer> , <pointee> ) + +or, + +.. code-block:: fortran + + pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ... + +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 ``*`` +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: + +.. code-block:: fortran + + integer ipt + pointer (ipt, iarr) + +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: + +.. code-block:: fortran + + real target(10) + real pointee(10) + pointer (ipt, pointee) + ipt = loc (target) + ipt = ipt + 1 + +The last statement does not set ``ipt`` to the address of +``target(1)``, as it would in C pointer arithmetic. Adding ``1`` +to ``ipt`` just adds one byte to the address stored in ``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 ``LOC()``. The ``LOC()`` function is equivalent to the +``&`` operator in C, except the address is cast to an integer type: + +.. code-block:: fortran + + 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 + +The pointer can also be set by a call to the ``MALLOC`` intrinsic +(see :ref:`MALLOC`). + +Cray pointees often are used to alias an existing variable. For +example: + +.. code-block:: fortran + + integer target(10) + integer iarr(10) + pointer (ipt, iarr) + ipt = loc(target) + +As long as ``ipt`` remains unchanged, ``iarr`` is now an alias for +``target``. The optimizer, however, will not detect this aliasing, so +it is unsafe to use ``iarr`` and ``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 +``ALLOCATABLE``, ``INTENT``, ``OPTIONAL``, ``DUMMY``, +``TARGET``, ``INTRINSIC``, or ``POINTER`` attributes. Pointers +may not have the ``DIMENSION``, ``POINTER``, ``TARGET``, +``ALLOCATABLE``, ``EXTERNAL``, or ``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: + +.. code-block:: fortran + + implicit none + external sub + pointer (subptr,subpte) + external subpte + subptr = loc(sub) + call subpte() + [...] + subroutine sub + [...] + end subroutine sub + +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. + +.. index:: CONVERT specifier + +.. _convert-specifier: + +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 ``CONVERT`` specifier on the ``OPEN`` statement. +See :ref:`gfortran_convert_unit`, for an alternative way of specifying +the data format via an environment variable. + +Valid values for ``CONVERT`` on most systems are: + +* ``CONVERT='NATIVE'`` Use the native format. This is the default. + +* ``CONVERT='SWAP'`` Swap between little- and big-endian. + +* ``CONVERT='LITTLE_ENDIAN'`` Use the little-endian representation + for unformatted files. + +* ``CONVERT='BIG_ENDIAN'`` Use the big-endian representation for + unformatted files. + +On POWER systems which support :option:`-mabi=ieeelongdouble`, +there are additional options, which can be combined with the others +with commas. Those are + +* ``CONVERT='R16_IEEE'`` Use IEEE 128-bit format for + ``REAL(KIND=16)``. + +* ``CONVERT='R16_IBM'`` Use IBM ``long double`` format for + real ``REAL(KIND=16)``. + +Using the option could look like this: + +.. code-block:: fortran + + open(file='big.dat',form='unformatted',access='sequential', & + convert='big_endian') + +The value of the conversion can be queried by using +``INQUIRE(CONVERT=ch)``. The values returned are +``'BIG_ENDIAN'`` and ``'LITTLE_ENDIAN'``. + +``CONVERT`` works between big- and little-endian for +``INTEGER`` values of all supported kinds and for ``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 ``REAL(KIND=10)`` and ``REAL(KIND=16)``, will +probably not work. + +*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. + +.. index:: OpenMP + +.. _openmp: + +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 +`OpenMP Application Program Interface v4.5 <https://openmp.org/specifications/>`_. + +To enable the processing of the OpenMP directive ``!$omp`` in +free-form source code; the ``c$omp``, ``*$omp`` and ``!$omp`` +directives in fixed form; the ``!$`` conditional compilation sentinels +in free form; and the ``c$``, ``*$`` and ``!$`` 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:`libgomp:top`. + +The OpenMP Fortran runtime library routines are provided both in a +form of a Fortran 90 module named ``omp_lib`` and in a form of +a Fortran ``include`` file named :samp:`omp_lib.h`. + +An example of a parallelized loop taken from Appendix A.1 of +the OpenMP Application Program Interface v2.5: + +.. code-block:: fortran + + 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 + +.. note:: + + :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. + +.. note:: + + 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. + +.. index:: OpenACC + +.. _openacc: + +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 +`OpenACC Application Programming +Interface v2.6 <https://www.openacc.org/>`_. + +To enable the processing of the OpenACC directive ``!$acc`` in +free-form source code; the ``c$acc``, ``*$acc`` and ``!$acc`` +directives in fixed form; the ``!$`` conditional compilation +sentinels in free form; and the ``c$``, ``*$`` and ``!$`` +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:`libgomp:top`. + +The OpenACC Fortran runtime library routines are provided both in a +form of a Fortran 90 module named ``openacc`` and in a form of a +Fortran ``include`` file named :samp:`openacc_lib.h`. + +.. index:: argument list functions, %VAL, %REF, %LOC + +.. _argument-list-functions: + +Argument list functions %VAL, %REF and %LOC +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GNU Fortran supports argument list functions ``%VAL``, ``%REF`` +and ``%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. + +``%VAL`` passes a scalar argument by value, ``%REF`` passes it by +reference and ``%LOC`` passes its memory location. Since gfortran +already passes scalar arguments by reference, ``%REF`` is in effect +a do-nothing. ``%LOC`` has the same effect as a Fortran pointer. + +An example of passing an argument by value to a C subroutine foo.: + +.. code-block:: fortran + + C + C prototype void foo_ (float x); + C + external foo + real*4 x + x = 3.14159 + call foo (%VAL (x)) + end + +For details refer to the g77 manual +https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/index.html#Top. + +Also, ``c_by_val.f`` and its partner ``c_by_val.c`` of the +GNU Fortran testsuite are worth a look. + +.. index:: EOF, BACKSPACE, REWIND + +.. _read-write-after-eof-marker: + +Read/Write after EOF marker +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some legacy codes rely on allowing ``READ`` or ``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 ``BACKSPACE`` or ``REWIND`` to properly position +the file before the EOF marker. As an extension, the run-time error may +be disabled using -std=legacy. + +.. index:: STRUCTURE, RECORD + +.. _structure-and-record: + +STRUCTURE and 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 ``STRUCTURE /``:samp:`{structure-name}` ``/`` +by ``TYPE`` :samp:`{type-name}`. Additionally, replace +``RECORD /``:samp:`{structure-name}` ``/`` by +``TYPE(``:samp:`{type-name}` ``)``. Finally, in the component access, +replace the period (``.``) by the percent sign (``%``). + +Here is an example of code using the non portable record structure syntax: + +.. code-block:: fortran + + ! 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) + +This code can easily be rewritten in the Fortran 90 syntax as following: + +.. code-block:: fortran + + ! ``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) + +GNU Fortran implements STRUCTURES like derived types with the following +rules and exceptions: + +* Structures act like derived types with the ``SEQUENCE`` attribute. + Otherwise they may contain no specifiers. + +* Structures may contain a special field with the name ``%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: + + .. code-block:: fortran + + structure /padded/ + character(4) start + character(8) %FILL + character(4) end + end structure + +* Structures may share names with other symbols. For example, the following + is invalid for derived types, but valid for structures: + + .. code-block:: fortran + + structure /header/ + ! ... + end structure + record /header/ header + +* Structure types may be declared nested within another parent structure. + The syntax is: + + .. code-block:: fortran + + structure /type-name/ + ... + structure [/<type-name>/] <field-list> + ... + + 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: + + .. code-block:: fortran + + 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 + +* Structures may contain ``UNION`` blocks. For more detail see the + section on :ref:`union-and-map`. + +* 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 + ``<literal-integer> * <constant-initializer>``. The value of the integer + indicates the number of times to repeat the constant initializer when expanding + the initializer list. + +.. index:: UNION, MAP + +.. _union-and-map: + +UNION and MAP +^^^^^^^^^^^^^ + +Unions are an old vendor extension which were commonly used with the +non-standard :ref:`structure-and-record` extensions. Use of ``UNION`` and +``MAP`` is automatically enabled with :option:`-fdec-structure`. + +A ``UNION`` declaration occurs within a structure; within the definition of +each union is a number of ``MAP`` blocks. Each ``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: + +.. code-block:: fortran + + 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!' + +The two maps share memory, and the size of the union is ultimately six bytes: + +.. code-block:: + + 0 1 2 3 4 5 6 Byte offset + ------------------------------- + | | | | | | | + ------------------------------- + + ^ W0 ^ W1 ^ W2 ^ + \-------/ \-------/ \-------/ + + ^ LONG ^ + \---------------------------/ + +Following is an example mirroring the layout of an Intel x86_64 register: + +.. code-block:: fortran + + 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' + +.. index:: intrinsics, integer + +.. _type-variants-for-integer-intrinsics: + +Type variants for integer intrinsics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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: + +.. code-block:: fortran + + B - INTEGER(kind=1) + I - INTEGER(kind=2) + J - INTEGER(kind=4) + K - INTEGER(kind=8) + +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: + +.. list-table:: + :header-rows: 1 + + * - Intrinsic + - B + - I + - J + - K + + * - ``ABS`` + - ``BABS`` + - ``IIABS`` + - ``JIABS`` + - ``KIABS`` + * - ``BTEST`` + - ``BBTEST`` + - ``BITEST`` + - ``BJTEST`` + - ``BKTEST`` + * - ``IAND`` + - ``BIAND`` + - ``IIAND`` + - ``JIAND`` + - ``KIAND`` + * - ``IBCLR`` + - ``BBCLR`` + - ``IIBCLR`` + - ``JIBCLR`` + - ``KIBCLR`` + * - ``IBITS`` + - ``BBITS`` + - ``IIBITS`` + - ``JIBITS`` + - ``KIBITS`` + * - ``IBSET`` + - ``BBSET`` + - ``IIBSET`` + - ``JIBSET`` + - ``KIBSET`` + * - ``IEOR`` + - ``BIEOR`` + - ``IIEOR`` + - ``JIEOR`` + - ``KIEOR`` + * - ``IOR`` + - ``BIOR`` + - ``IIOR`` + - ``JIOR`` + - ``KIOR`` + * - ``ISHFT`` + - ``BSHFT`` + - ``IISHFT`` + - ``JISHFT`` + - ``KISHFT`` + * - ``ISHFTC`` + - ``BSHFTC`` + - ``IISHFTC`` + - ``JISHFTC`` + - ``KISHFTC`` + * - ``MOD`` + - ``BMOD`` + - ``IMOD`` + - ``JMOD`` + - ``KMOD`` + * - ``NOT`` + - ``BNOT`` + - ``INOT`` + - ``JNOT`` + - ``KNOT`` + * - ``REAL`` + - ``--`` + - ``FLOATI`` + - ``FLOATJ`` + - ``FLOATK`` + +.. _automatic-and-static-attributes: + +AUTOMATIC and STATIC attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +With :option:`-fdec-static` GNU Fortran supports the DEC extended attributes +``STATIC`` and ``AUTOMATIC`` to provide explicit specification of entity +storage. These follow the syntax of the Fortran standard ``SAVE`` attribute. + +``STATIC`` is exactly equivalent to ``SAVE``, and specifies that +an entity should be allocated in static memory. As an example, ``STATIC`` +local variables will retain their values across multiple calls to a function. + +Entities marked ``AUTOMATIC`` will be stack automatic whenever possible. +``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 ``SAVE`` statements. + +Examples: + +.. code-block:: fortran + + subroutine f + integer, automatic :: i ! automatic variable + integer x, y ! static variables + save + ... + endsubroutine + +.. code-block:: fortran + + 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 + +.. code-block:: fortran + + ! Compiled with -fno-automatic + subroutine f + integer a, b, c, d + automatic :: a + ! a is automatic; b, c, and d are static + endsubroutine + +.. index:: intrinsics, math, intrinsics, trigonometric functions + +.. _extended-math-intrinsics: + +Extended math intrinsics +^^^^^^^^^^^^^^^^^^^^^^^^ + +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: + +.. list-table:: + :header-rows: 1 + + * - Radians + - Degrees + + * - ``ACOS`` + - ``ACOSD`` \* + * - ``ASIN`` + - ``ASIND`` \* + * - ``ATAN`` + - ``ATAND`` \* + * - ``ATAN2`` + - ``ATAN2D`` \* + * - ``COS`` + - ``COSD`` \* + * - ``COTAN`` \* + - ``COTAND`` \* + * - ``SIN`` + - ``SIND`` \* + * - ``TAN`` + - ``TAND`` \* + +\* 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). + +.. index:: form feed whitespace + +.. _form-feed-as-whitespace: + +Form feed as 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. + +.. index:: type alias print + +.. _type-as-an-alias-for-print: + +TYPE as an alias for PRINT +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For compatibility, GNU Fortran will interpret ``TYPE`` statements as +``PRINT`` statements with the flag :option:`-fdec`. With this flag asserted, +the following two examples are equivalent: + +.. code-block:: fortran + + TYPE *, 'hello world' + +.. code-block:: fortran + + PRINT *, 'hello world' + +.. index:: LOC + +.. _%loc-as-an-rvalue: + +%LOC as an rvalue +^^^^^^^^^^^^^^^^^ + +Normally ``%LOC`` is allowed only in parameter lists. However the intrinsic +function ``LOC`` does the same thing, and is usable as the right-hand-side of +assignments. For compatibility, GNU Fortran supports the use of ``%LOC`` as +an alias for the builtin ``LOC`` with :option:`-std=legacy`. With this +feature enabled the following two examples are equivalent: + +.. code-block:: fortran + + integer :: i, l + l = %loc(i) + call sub(l) + +.. code-block:: fortran + + integer :: i + call sub(%loc(i)) + +.. index:: operators, xor + +.. _.xor.-operator: + +.XOR. operator +^^^^^^^^^^^^^^ + +GNU Fortran supports ``.XOR.`` as a logical operator with ``-std=legacy`` +for compatibility with legacy code. ``.XOR.`` is equivalent to +``.NEQV.``. That is, the output is true if and only if the inputs differ. + +.. index:: logical, bitwise + +.. _bitwise-logical-operators: + +Bitwise logical operators +^^^^^^^^^^^^^^^^^^^^^^^^^ + +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: + +.. code-block:: fortran + + INTEGER :: i, j + i = z'33' + j = z'cc' + print *, i .AND. j + +In this example, compiled with :option:`-fdec`, GNU Fortran will +replace the ``.AND.`` operation with a call to the intrinsic +function, yielding the bitwise-and of ``i`` and ``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, +``.TRUE.`` is converted to ``1`` and ``.FALSE.`` to ``0``. + +Here is the mapping of logical operator to bitwise intrinsic used with +:option:`-fdec` : + +.. list-table:: + :header-rows: 1 + + * - Operator + - Intrinsic + - Bitwise operation + + * - ``.NOT.`` + - ``NOT`` + - complement + * - ``.AND.`` + - ``IAND`` + - intersection + * - ``.OR.`` + - ``IOR`` + - union + * - ``.NEQV.`` + - ``IEOR`` + - exclusive or + * - ``.EQV.`` + - ``NOT(IEOR)`` + - complement of exclusive or + +.. _extended-i-o-specifiers: + +Extended I/O specifiers +^^^^^^^^^^^^^^^^^^^^^^^ + +GNU Fortran supports the additional legacy I/O specifiers +``CARRIAGECONTROL``, ``READONLY``, and ``SHARE`` with the +compile flag :option:`-fdec`, for compatibility. + +.. envvar:: CARRIAGECONTROL + + The ``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 ``CARRAIGECONTROL`` is specified upon + opening a unit for formatted writing, the exact ``CARRIAGECONTROL`` setting + determines what characters to write between output records. The syntax is: + + .. code-block:: fortran + + OPEN(..., CARRIAGECONTROL=cc) + + Where *cc* is a character expression that evaluates to one of the + following values: + + .. list-table:: + + * - ``'LIST'`` + - One line feed between records (default) + * - ``'FORTRAN'`` + - Legacy interpretation of the first character (see below) + * - ``'NONE'`` + - No separator between records + + With ``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: + + .. list-table:: + :header-rows: 1 + + * - Leading character + - Meaning + - Output separating character(s) + + * - ``'+'`` + - Overprinting + - Carriage return only + * - ``'-'`` + - New line + - Line feed and carriage return + * - ``'0'`` + - Skip line + - Two line feeds and carriage return + * - ``'1'`` + - New page + - Form feed and carriage return + * - ``'$'`` + - Prompting + - Line feed (no carriage return) + * - ``CHAR(0)`` + - Overprinting (no advance) + - None + +.. envvar:: READONLY + + The ``READONLY`` specifier may be given upon opening a unit, and is + equivalent to specifying ``ACTION='READ'``, except that the file may not be + deleted on close (i.e. ``CLOSE`` with ``STATUS="DELETE"``). The syntax + is: + + .. code-block:: fortran + + OPEN(..., READONLY) + +.. envvar:: SHARE + + The ``SHARE`` specifier allows system-level locking on a unit upon opening + it for controlled access from multiple processes/threads. The ``SHARE`` + specifier has several forms: + + .. code-block:: fortran + + OPEN(..., SHARE=sh) + OPEN(..., SHARED) + OPEN(..., NOSHARED) + + Where *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 *sh*: + + .. list-table:: + :header-rows: 1 + + * - Explicit form + - Short form + - Meaning + + * - ``SHARE='DENYRW'`` + - ``NOSHARED`` + - Exclusive (write) lock + * - ``SHARE='DENYNONE'`` + - ``SHARED`` + - Shared (read) lock + + 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 ``fcntl``. Consult your corresponding operating + system's manual pages for further details. Locking via ``SHARE=`` is not + supported on other systems. + +.. index:: PARAMETER + +.. _legacy-parameter-statements: + +Legacy PARAMETER statements +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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: + +.. code-block:: fortran + + implicit real (E) + parameter e = 2.718282 + real c + parameter c = 3.0e8 + +.. index:: exponent + +.. _default-exponents: + +Default exponents +^^^^^^^^^^^^^^^^^ + +For compatibility, GNU Fortran supports a default exponent of zero in real +constants with :option:`-fdec`. For example, ``9e`` would be +interpreted as ``9e0``, rather than an error.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/extensions-not-implemented-in-gnu-fortran.rst b/gcc/fortran/doc/gfortran/extensions-not-implemented-in-gnu-fortran.rst new file mode 100644 index 0000000..33bbd7b --- /dev/null +++ b/gcc/fortran/doc/gfortran/extensions-not-implemented-in-gnu-fortran.rst @@ -0,0 +1,186 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: extensions, not implemented + +.. _extensions-not-implemented-in-gnu-fortran: + +Extensions not implemented in GNU Fortran +***************************************** + +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. + +.. More can be found here: + - https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html + - the list of Fortran and libgfortran bugs closed as WONTFIX: + http://tinyurl.com/2u4h5y + +.. toctree:: + :maxdepth: 2 + + +.. index:: ENCODE, DECODE + +.. _encode-and-decode-statements: + +ENCODE and DECODE statements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GNU Fortran does not support the ``ENCODE`` and ``DECODE`` +statements. These statements are best replaced by ``READ`` and +``WRITE`` statements involving internal files (``CHARACTER`` +variables and arrays), which have been part of the Fortran standard since +Fortran 77. For example, replace a code fragment like + +.. code-block:: fortran + + 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)) + +with the following: + +.. code-block:: fortran + + 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)) + +Similarly, replace a code fragment like + +.. code-block:: fortran + + 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)) + +with the following: + +.. code-block:: fortran + + 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)) + +.. index:: FORMAT + +.. _variable-format-expressions: + +Variable FORMAT expressions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A variable ``FORMAT`` expression is format statement which includes +angle brackets enclosing a Fortran expression: ``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: + +.. code-block:: fortran + + WRITE(6,20) INT1 + 20 FORMAT(I<N+1>) + +with the following: + +.. code-block:: fortran + + c Variable declaration + CHARACTER(LEN=20) FMT + c + c Other code here... + c + WRITE(FMT,'("(I", I0, ")")') N+1 + WRITE(6,FMT) INT1 + +or with: + +.. code-block:: fortran + + c Variable declaration + CHARACTER(LEN=20) FMT + c + c Other code here... + c + WRITE(FMT,*) N+1 + WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1 + +.. index:: Complex function + +.. _alternate-complex-function-syntax: + +Alternate complex function syntax +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some Fortran compilers, including :command:`g77`, let the user declare +complex functions with the syntax ``COMPLEX FUNCTION name*16()``, as +well as ``COMPLEX*16 FUNCTION name()``. Both are non-standard, legacy +extensions. :command:`gfortran` accepts the latter form, which is more +common, but not the former. + +.. index:: VOLATILE, COMMON + +.. _volatile-common-blocks: + +Volatile COMMON blocks +^^^^^^^^^^^^^^^^^^^^^^ + +Some Fortran compilers, including :command:`g77`, let the user declare +``COMMON`` with the ``VOLATILE`` attribute. This is +invalid standard Fortran syntax and is not supported by +:command:`gfortran`. Note that :command:`gfortran` accepts +``VOLATILE`` variables in ``COMMON`` blocks since revision 4.3. + +.. index:: NAME + +.. _open(-...-name=): + +OPEN( ... NAME=) +^^^^^^^^^^^^^^^^ + +Some Fortran compilers, including :command:`g77`, let the user declare +``OPEN( ... NAME=)``. This is +invalid standard Fortran syntax and is not supported by +:command:`gfortran`. ``OPEN( ... NAME=)`` should be replaced +with ``OPEN( ... FILE=)``. + +.. index:: Q edit descriptor + +.. _q-edit-descriptor: + +Q edit descriptor +^^^^^^^^^^^^^^^^^ + +Some Fortran compilers provide the ``Q`` edit descriptor, which +transfers the number of characters left within an input record into an +integer variable. + +A direct replacement of the ``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 ``Q`` may be to read the whole line into a +character variable and then counting the number of non-blank +characters left using ``LEN_TRIM``. Another method may be to use +formatted stream, read the data up to the position where the ``Q`` +descriptor occurred, use ``INQUIRE`` to get the file position, +count the characters up to the next ``NEW_LINE`` and then start +reading from the position marked previously.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/extensions.rst b/gcc/fortran/doc/gfortran/extensions.rst new file mode 100644 index 0000000..c151fc6 --- /dev/null +++ b/gcc/fortran/doc/gfortran/extensions.rst @@ -0,0 +1,24 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: extensions + +.. _extensions: + +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. + +.. toctree:: + :maxdepth: 2 + + extensions-implemented-in-gnu-fortran + extensions-not-implemented-in-gnu-fortran
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/function-abi-documentation.rst b/gcc/fortran/doc/gfortran/function-abi-documentation.rst new file mode 100644 index 0000000..a26ea3f --- /dev/null +++ b/gcc/fortran/doc/gfortran/function-abi-documentation.rst @@ -0,0 +1,1526 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _function-abi-documentation: + +Function ABI Documentation +************************** + +.. toctree:: + :maxdepth: 2 + + +.. index:: Coarray, _gfortran_caf_init + +.. _gfortran_caf_init: + +_gfortran_caf_init --- Initialiation function +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_init (int *argc, char ***argv) + + 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 ``NULL`` pointers as argument; if non- ``NULL``, + the library is permitted to modify the arguments. + + :param argc: + intent(inout) An integer pointer with the number of + arguments passed to the program or ``NULL``. + + :param argv: + intent(inout) A pointer to an array of strings with the + command-line arguments or ``NULL``. + + .. note:: + + 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. + +.. index:: Coarray, _gfortran_caf_finish + +.. _gfortran_caf_finish: + +_gfortran_caf_finish --- Finalization function +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_finish (void) + + This function is called at the end of the Fortran main program, if it has + been compiled with the :option:`-fcoarray=lib` option. + + .. note:: + + 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. + +.. index:: Coarray, _gfortran_caf_this_image + +.. _gfortran_caf_this_image: + +_gfortran_caf_this_image --- Querying the image number +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: int _gfortran_caf_this_image (int distance) + + This function returns the current image number, which is a positive number. + + :param distance: + As specified for the ``this_image`` intrinsic + in TS18508. Shall be a non-negative number. + + .. note:: + + If the Fortran intrinsic ``this_image`` is invoked without an argument, which + is the only permitted form in Fortran 2008, GCC passes ``0`` as + first argument. + +.. index:: Coarray, _gfortran_caf_num_images + +.. _gfortran_caf_num_images: + +_gfortran_caf_num_images --- Querying the maximal number of images +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: int _gfortran_caf_num_images(int distance, int failed) + + This function returns the number of images in the current team, if + :samp:`{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. + + :param distance: + the distance from this image to the ancestor. + Shall be positive. + + :param failed: + shall be -1, 0, or 1 + + .. note:: + + This function follows TS18508. If the num_image intrinsic has no arguments, + then the compiler passes ``distance=0`` and ``failed=-1`` to the function. + +.. index:: Coarray, _gfortran_caf_image_status + +.. _gfortran_caf_image_status: + +_gfortran_caf_image_status --- Query the status of an image +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: int _gfortran_caf_image_status (int image, caf_team_t * team) + + Get the status of the image given by the id :samp:`{image}` of the team given by + :samp:`{team}`. Valid results are zero, for image is ok, ``STAT_STOPPED_IMAGE`` + from the ISO_FORTRAN_ENV module to indicate that the image has been stopped and + ``STAT_FAILED_IMAGE`` also from ISO_FORTRAN_ENV to indicate that the image + has executed a ``FAIL IMAGE`` statement. + + :param image: + the positive scalar id of the image in the current TEAM. + + :param team: + optional; team on the which the inquiry is to be + performed. + + .. note:: + + This function follows TS18508. Because team-functionality is not yet + implemented a null-pointer is passed for the :samp:`{team}` argument at the moment. + +.. index:: Coarray, _gfortran_caf_failed_images + +.. _gfortran_caf_failed_images: + +_gfortran_caf_failed_images --- Get an array of the indexes of the failed images +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: int _gfortran_caf_failed_images (caf_team_t * team, int * kind) + + Get an array of image indexes in the current :samp:`{team}` that have failed. The + array is sorted ascendingly. When :samp:`{team}` is not provided the current team + is to be used. When :samp:`{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. + + :param team: + optional; team on the which the inquiry is to be + performed. + + :param image: + optional; the kind of the resulting integer array. + + .. note:: + + This function follows TS18508. Because team-functionality is not yet + implemented a null-pointer is passed for the :samp:`{team}` argument at the moment. + +.. index:: Coarray, _gfortran_caf_stopped_images + +.. _gfortran_caf_stopped_images: + +_gfortran_caf_stopped_images --- Get an array of the indexes of the stopped images +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: int _gfortran_caf_stopped_images (caf_team_t * team, int * kind) + + Get an array of image indexes in the current :samp:`{team}` that have stopped. The + array is sorted ascendingly. When :samp:`{team}` is not provided the current team + is to be used. When :samp:`{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. + + :param team: + optional; team on the which the inquiry is to be + performed. + + :param image: + optional; the kind of the resulting integer array. + + .. note:: + + This function follows TS18508. Because team-functionality is not yet + implemented a null-pointer is passed for the :samp:`{team}` argument at the moment. + +.. index:: Coarray, _gfortran_caf_register + +.. _gfortran_caf_register: + +_gfortran_caf_register --- Registering coarrays +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + Registers memory for a coarray and creates a token to identify the coarray. The + routine is called for both coarrays with ``SAVE`` attribute and using an + explicit ``ALLOCATE`` statement. If an error occurs and :samp:`{STAT}` is a + ``NULL`` pointer, the function shall abort with printing an error message + and starting the error termination. If no error occurs and :samp:`{STAT}` is + present, it shall be set to zero. Otherwise, it shall be set to a positive + value and, if not- ``NULL``, :samp:`{ERRMSG}` shall be set to a string describing + the failure. The routine shall register the memory provided in the + ``DATA`` -component of the array descriptor :samp:`{DESC}`, when that component + is non- ``NULL``, else it shall allocate sufficient memory and provide a + pointer to it in the ``DATA`` -component of :samp:`{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 ``_gfortran_caf_register``. + When an array is to be allocated the descriptor persists. + + :param size: + For normal coarrays, the byte size of the coarray to be + allocated; for lock types and event types, the number of elements. + + :param type: + one of the caf_register_t types. + + :param token: + intent(out) An opaque pointer identifying the coarray. + + :param desc: + intent(inout) The (pseudo) array descriptor. + + :param stat: + intent(out) For allocatable coarrays, stores the STAT=; + may be ``NULL`` + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be ``NULL`` + + :param errmsg_len: + the buffer size of errmsg. + + .. note:: + + 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 + :samp:`{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 + (``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. + +.. index:: Coarray, _gfortran_caf_deregister + +.. _gfortran_caf_deregister: + +_gfortran_caf_deregister --- Deregistering coarrays +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void caf_deregister (caf_token_t *token, caf_deregister_t type, int *stat, char *errmsg, size_t errmsg_len) + + 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 :samp:`{STAT}` variable is + not null. The library is only expected to free memory it allocated itself + during a call to ``_gfortran_caf_register``. + + :param token: + the token to free. + + :param type: + the type of action to take for the coarray. A + ``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. + + :param stat: + intent(out) Stores the STAT=; may be NULL + + :param errmsg: + intent(out) When an error occurs, this will be set + to an error message; may be NULL + + :param errmsg_len: + the buffer size of errmsg. + + .. note:: + + 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. + +.. index:: Coarray, _gfortran_caf_is_present + +.. _gfortran_caf_is_present: + +_gfortran_caf_is_present --- Query whether an allocatable or pointer component in a derived type coarray is allocated +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_is_present (caf_token_t token, int image_index, gfc_reference_t *ref) + + Used to query the coarray library whether an allocatable component in a derived + type coarray is allocated on a remote image. + + :param token: + An opaque pointer identifying the coarray. + + :param image_index: + The ID of the remote image; must be a positive + number. + + :param ref: + 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. + +.. index:: Coarray, _gfortran_caf_send + +.. _gfortran_caf_send: + +_gfortran_caf_send --- Sending data from a local image to a remote image +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + Called to send a scalar, an array section or a whole array from a local + to a remote image identified by the image_index. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param offset: + intent(in) By which amount of bytes the actual data is + shifted compared to the base address of the coarray. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number. + + :param dest: + intent(in) Array descriptor for the remote image for the + bounds and the size. The ``base_addr`` shall not be accessed. + + :param dst_vector: + 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. + + :param src: + intent(in) Array descriptor of the local array to be + transferred to the remote image + + :param dst_kind: + intent(in) Kind of the destination argument + + :param src_kind: + intent(in) Kind of the source argument + + :param may_require_tmp: + intent(in) The variable is ``false`` when + it is known at compile time that the :samp:`{dest}` and :samp:`{src}` either cannot + overlap or overlap (fully or partially) such that walking :samp:`{src}` and + :samp:`{dest}` in element wise element order (honoring the stride value) will not + lead to wrong results. Otherwise, the value is ``true``. + + :param stat: + 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. + + .. note:: + + It is permitted to have :samp:`{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 + ``memmove`` which handles (partially) overlapping memory. If + :samp:`{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 ``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. + +.. index:: Coarray, _gfortran_caf_get + +.. _gfortran_caf_get: + +_gfortran_caf_get --- Getting data from a remote image +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + Called to get an array section or a whole array from a remote, + image identified by the image_index. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param offset: + intent(in) By which amount of bytes the actual data is + shifted compared to the base address of the coarray. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number. + + :param dest: + intent(out) Array descriptor of the local array to store + the data retrieved from the remote image + + :param src: + intent(in) Array descriptor for the remote image for the + bounds and the size. The ``base_addr`` shall not be accessed. + + :param src_vector: + intent(in) If not NULL, it contains the vector + subscript of the source array; the values are relative to the dimension + triplet of the :samp:`{src}` argument. + + :param dst_kind: + intent(in) Kind of the destination argument + + :param src_kind: + intent(in) Kind of the source argument + + :param may_require_tmp: + intent(in) The variable is ``false`` when + it is known at compile time that the :samp:`{dest}` and :samp:`{src}` either cannot + overlap or overlap (fully or partially) such that walking :samp:`{src}` and + :samp:`{dest}` in element wise element order (honoring the stride value) will not + lead to wrong results. Otherwise, the value is ``true``. + + :param stat: + 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. + + .. note:: + + It is permitted to have :samp:`{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 + ``memmove`` which handles (partially) overlapping memory. If + :samp:`{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 ``memmove`` takes care of overlap issues). + + Note that the library has to handle numeric-type conversion and for strings, + padding and different character kinds. + +.. index:: Coarray, _gfortran_caf_sendget + +.. _gfortran_caf_sendget: + +_gfortran_caf_sendget --- Sending data between remote images +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + Called to send a scalar, an array section or a whole array from a remote image + identified by the :samp:`{src_image_index}` to a remote image identified by the + :samp:`{dst_image_index}`. + + :param dst_token: + intent(in) An opaque pointer identifying the + destination coarray. + + :param dst_offset: + intent(in) By which amount of bytes the actual data + is shifted compared to the base address of the destination coarray. + + :param dst_image_index: + intent(in) The ID of the destination remote + image; must be a positive number. + + :param dest: + intent(in) Array descriptor for the destination + remote image for the bounds and the size. The ``base_addr`` shall not be + accessed. + + :param dst_vector: + intent(int) If not NULL, it contains the vector + subscript of the destination array; the values are relative to the dimension + triplet of the :samp:`{dest}` argument. + + :param src_token: + intent(in) An opaque pointer identifying the source + coarray. + + :param src_offset: + intent(in) By which amount of bytes the actual data + is shifted compared to the base address of the source coarray. + + :param src_image_index: + intent(in) The ID of the source remote image; + must be a positive number. + + :param src: + intent(in) Array descriptor of the local array to be + transferred to the remote image. + + :param src_vector: + intent(in) Array descriptor of the local array to + be transferred to the remote image + + :param dst_kind: + intent(in) Kind of the destination argument + + :param src_kind: + intent(in) Kind of the source argument + + :param may_require_tmp: + intent(in) The variable is ``false`` when + it is known at compile time that the :samp:`{dest}` and :samp:`{src}` either cannot + overlap or overlap (fully or partially) such that walking :samp:`{src}` and + :samp:`{dest}` in element wise element order (honoring the stride value) will not + lead to wrong results. Otherwise, the value is ``true``. + + :param stat: + 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. + + .. note:: + + It is permitted to have the same image index for both :samp:`{src_image_index}` and + :samp:`{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 ``memmove`` which handles (partially) + overlapping memory. If :samp:`{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 ``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. + +.. index:: Coarray, _gfortran_caf_send_by_ref + +.. _gfortran_caf_send_by_ref: + +_gfortran_caf_send_by_ref --- Sending data from a local image to a remote image with enhanced referencing options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + Called to send a scalar, an array section or a whole array from a local to a + remote image identified by the :samp:`{image_index}`. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number. + + :param src: + intent(in) Array descriptor of the local array to be + transferred to the remote image + + :param refs: + intent(in) The references on the remote array to store + the data given by src. Guaranteed to have at least one entry. + + :param dst_kind: + intent(in) Kind of the destination argument + + :param src_kind: + intent(in) Kind of the source argument + + :param may_require_tmp: + intent(in) The variable is ``false`` when + it is known at compile time that the :samp:`{dest}` and :samp:`{src}` either cannot + overlap or overlap (fully or partially) such that walking :samp:`{src}` and + :samp:`{dest}` in element wise element order (honoring the stride value) will not + lead to wrong results. Otherwise, the value is ``true``. + + :param dst_reallocatable: + 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. + + :param stat: + 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. + + :param dst_type: + 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. + + .. note:: + + It is permitted to have :samp:`{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 + ``memmove`` which handles (partially) overlapping memory. If + :samp:`{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 ``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. + +.. index:: Coarray, _gfortran_caf_get_by_ref + +.. _gfortran_caf_get_by_ref: + +_gfortran_caf_get_by_ref --- Getting data from a remote image using enhanced references +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + Called to get a scalar, an array section or a whole array from a remote image + identified by the :samp:`{image_index}`. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number. + + :param refs: + intent(in) The references to apply to the remote structure + to get the data. + + :param dst: + intent(in) Array descriptor of the local array to store + the data transferred from the remote image. May be reallocated where needed + and when :samp:`{DST_REALLOCATABLE}` allows it. + + :param dst_kind: + intent(in) Kind of the destination argument + + :param src_kind: + intent(in) Kind of the source argument + + :param may_require_tmp: + intent(in) The variable is ``false`` when + it is known at compile time that the :samp:`{dest}` and :samp:`{src}` either cannot + overlap or overlap (fully or partially) such that walking :samp:`{src}` and + :samp:`{dest}` in element wise element order (honoring the stride value) will not + lead to wrong results. Otherwise, the value is ``true``. + + :param dst_reallocatable: + intent(in) Set when :samp:`{DST}` is of + allocatable or pointer type and its refs allow reallocation, i.e., the full + array or a component is referenced. + + :param stat: + 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. + + :param src_type: + 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. + + .. note:: + + It is permitted to have ``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 + ``memmove`` which handles (partially) overlapping memory. If + :samp:`{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 ``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. + +.. index:: Coarray, _gfortran_caf_sendget_by_ref + +.. _gfortran_caf_sendget_by_ref: + +_gfortran_caf_sendget_by_ref --- Sending data between remote images using enhanced references on both sides +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + Called to send a scalar, an array section or a whole array from a remote image + identified by the :samp:`{src_image_index}` to a remote image identified by the + :samp:`{dst_image_index}`. + + :param dst_token: + intent(in) An opaque pointer identifying the + destination coarray. + + :param dst_image_index: + intent(in) The ID of the destination remote + image; must be a positive number. + + :param dst_refs: + intent(in) The references on the remote array to store + the data given by the source. Guaranteed to have at least one entry. + + :param src_token: + intent(in) An opaque pointer identifying the source + coarray. + + :param src_image_index: + intent(in) The ID of the source remote image; + must be a positive number. + + :param src_refs: + intent(in) The references to apply to the remote + structure to get the data. + + :param dst_kind: + intent(in) Kind of the destination argument + + :param src_kind: + intent(in) Kind of the source argument + + :param may_require_tmp: + intent(in) The variable is ``false`` when + it is known at compile time that the :samp:`{dest}` and :samp:`{src}` either cannot + overlap or overlap (fully or partially) such that walking :samp:`{src}` and + :samp:`{dest}` in element wise element order (honoring the stride value) will not + lead to wrong results. Otherwise, the value is ``true``. + + :param dst_stat: + intent(out) when non- ``NULL`` give the result of + the send-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. + + :param src_stat: + intent(out) When non- ``NULL`` give the result of + the get-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. + + :param dst_type: + 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. + + :param src_type: + 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. + + .. note:: + + It is permitted to have the same image index for both :samp:`{src_image_index}` and + :samp:`{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 ``memmove`` which handles (partially) + overlapping memory. If :samp:`{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 ``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. + +.. index:: Coarray, _gfortran_caf_lock + +.. _gfortran_caf_lock: + +_gfortran_caf_lock --- Locking a lock variable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + 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 :samp:`{acquired_lock}` + is ``NULL``, the function returns after having obtained the lock. If it is + non- ``NULL``, then :samp:`{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. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param index: + intent(in) Array index; first array index is 0. For + scalars, it is always 0. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number. + + :param acquired_lock: + intent(out) If not NULL, it returns whether lock + could be obtained. + + :param stat: + intent(out) Stores the STAT=; may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param errmsg_len: + intent(in) the buffer size of errmsg + + .. note:: + + 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. + +.. index:: Coarray, _gfortran_caf_unlock + +.. _gfortran_caf_unlock: + +_gfortran_caf_lock --- Unlocking a lock variable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_unlock (caf_token_t token, size_t index, int image_index, int *stat, char *errmsg, size_t errmsg_len) + + 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. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param index: + intent(in) Array index; first array index is 0. For + scalars, it is always 0. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number. + + :param stat: + intent(out) For allocatable coarrays, stores the STAT=; + may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param errmsg_len: + intent(in) the buffer size of errmsg + + .. note:: + + 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. + +.. index:: Coarray, _gfortran_caf_event_post + +.. _gfortran_caf_event_post: + +_gfortran_caf_event_post --- Post an event +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_event_post (caf_token_t token, size_t index, int image_index, int *stat, char *errmsg, size_t errmsg_len) + + Increment the event count of the specified event variable. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param index: + intent(in) Array index; first array index is 0. For + scalars, it is always 0. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number; zero indicates the current image, when accessed noncoindexed. + + :param stat: + intent(out) Stores the STAT=; may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param errmsg_len: + intent(in) the buffer size of errmsg + + .. note:: + + 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 ``event_wait`` on the remote + image returns. + +.. index:: Coarray, _gfortran_caf_event_wait + +.. _gfortran_caf_event_wait: + +_gfortran_caf_event_wait --- Wait that an event occurred +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_event_wait (caf_token_t token, size_t index, int until_count, int *stat, char *errmsg, size_t errmsg_len) + + Wait until the event count has reached at least the specified + :samp:`{until_count}` ; if so, atomically decrement the event variable by this + amount and return. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param index: + intent(in) Array index; first array index is 0. For + scalars, it is always 0. + + :param until_count: + intent(in) The number of events which have to be + available before the function returns. + + :param stat: + intent(out) Stores the STAT=; may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param errmsg_len: + intent(in) the buffer size of errmsg + + .. note:: + + 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 :samp:`{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 ``event_wait`` on the remote + image returns. + +.. index:: Coarray, _gfortran_caf_event_query + +.. _gfortran_caf_event_query: + +_gfortran_caf_event_query --- Query event count +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_event_query (caf_token_t token, size_t index, int image_index, int *count, int *stat) + + Return the event count of the specified event variable. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param index: + intent(in) Array index; first array index is 0. For + scalars, it is always 0. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number; zero indicates the current image when accessed noncoindexed. + + :param count: + intent(out) The number of events currently posted to + the event variable. + + :param stat: + intent(out) Stores the STAT=; may be NULL. + + .. note:: + + The typical use is to check the local event variable to only call + ``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. + +.. index:: Coarray, _gfortran_caf_sync_all + +.. _gfortran_caf_sync_all: + +_gfortran_caf_sync_all --- All-image barrier +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_sync_all (int *stat, char *errmsg, size_t errmsg_len) + + 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. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param errmsg_len: + intent(in) the buffer size of errmsg + +.. index:: Coarray, _gfortran_caf_sync_images + +.. _gfortran_caf_sync_images: + +_gfortran_caf_sync_images --- Barrier for selected images +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_sync_images (int count, int images[], int *stat, char *errmsg, size_t errmsg_len) + + 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 ``sync images(*)``) while those only wait for that specific + image. Additionally, ``sync images`` ensures that all pending data + transfers of previous segments have completed. + + :param count: + intent(in) The number of images which are provided in + the next argument. For a zero-sized array, the value is zero. For + ``sync images (*)``, the value is -1. + + :param images: + intent(in) An array with the images provided by the + user. If :samp:`{count}` is zero, a NULL pointer is passed. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param errmsg_len: + intent(in) the buffer size of errmsg + +.. index:: Coarray, _gfortran_caf_sync_memory + +.. _gfortran_caf_sync_memory: + +_gfortran_caf_sync_memory --- Wait for completion of segment-memory operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_sync_memory (int *stat, char *errmsg, size_t errmsg_len) + + Acts as optimization barrier between different segments. It also ensures that + all pending memory operations of this image have been completed. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param errmsg_len: + intent(in) the buffer size of errmsg + + .. note:: + + A simple implementation could be + ``__asm__ __volatile__ ("":::"memory")`` to prevent code movements. + +.. index:: Coarray, _gfortran_caf_error_stop + +.. _gfortran_caf_error_stop: + +_gfortran_caf_error_stop --- Error termination with exit code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_error_stop (int error) + + Invoked for an ``ERROR STOP`` statement which has an integer argument. The + function should terminate the program with the specified exit code. + + :param error: + intent(in) The exit status to be used. + +.. index:: Coarray, _gfortran_caf_error_stop_str + +.. _gfortran_caf_error_stop_str: + +_gfortran_caf_error_stop_str --- Error termination with string +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_error_stop (const char *string, size_t len) + + Invoked for an ``ERROR STOP`` statement which has a string as argument. The + function should terminate the program with a nonzero-exit code. + + :param string: + intent(in) the error message (not zero terminated) + + :param len: + intent(in) the length of the string + +.. index:: Coarray, _gfortran_caf_fail_image + +.. _gfortran_caf_fail_image: + +_gfortran_caf_fail_image --- Mark the image failed and end its execution +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_fail_image () + + Invoked for an ``FAIL IMAGE`` statement. The function should terminate the + current image. + + .. note:: + + This function follows TS18508. + +.. index:: Coarray, _gfortran_caf_atomic_define + +.. _gfortran_caf_atomic_define: + +_gfortran_caf_atomic_define --- Atomic variable assignment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_atomic_define (caf_token_t token, size_t offset, int image_index, void *value, int *stat, int type, int kind) + + Assign atomically a value to an integer or logical variable. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param offset: + intent(in) By which amount of bytes the actual data is + shifted compared to the base address of the coarray. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number; zero indicates the current image when used noncoindexed. + + :param value: + intent(in) the value to be assigned, passed by reference + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param type: + intent(in) The data type, i.e. ``BT_INTEGER`` (1) or + ``BT_LOGICAL`` (2). + + :param kind: + intent(in) The kind value (only 4; always ``int``) + +.. index:: Coarray, _gfortran_caf_atomic_ref + +.. _gfortran_caf_atomic_ref: + +_gfortran_caf_atomic_ref --- Atomic variable reference +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_atomic_ref (caf_token_t token, size_t offset, int image_index, void *value, int *stat, int type, int kind) + + Reference atomically a value of a kind-4 integer or logical variable. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param offset: + intent(in) By which amount of bytes the actual data is + shifted compared to the base address of the coarray. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number; zero indicates the current image when used noncoindexed. + + :param value: + intent(out) The variable assigned the atomically + referenced variable. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param type: + the data type, i.e. ``BT_INTEGER`` (1) or + ``BT_LOGICAL`` (2). + + :param kind: + The kind value (only 4; always ``int``) + +.. index:: Coarray, _gfortran_caf_atomic_cas + +.. _gfortran_caf_atomic_cas: + +_gfortran_caf_atomic_cas --- Atomic compare and swap +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + 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. + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param offset: + intent(in) By which amount of bytes the actual data is + shifted compared to the base address of the coarray. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number; zero indicates the current image when used noncoindexed. + + :param old: + intent(out) The value which the atomic variable had + just before the cas operation. + + :param compare: + intent(in) The value used for comparision. + + :param new_val: + intent(in) The new value for the atomic variable, + assigned to the atomic variable, if ``compare`` equals the value of the + atomic variable. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param type: + intent(in) the data type, i.e. ``BT_INTEGER`` (1) or + ``BT_LOGICAL`` (2). + + :param kind: + intent(in) The kind value (only 4; always ``int``) + +.. index:: Coarray, _gfortran_caf_atomic_op + +.. _gfortran_caf_atomic_op: + +_gfortran_caf_atomic_op --- Atomic operation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + Apply an operation atomically to an atomic integer or logical variable. + After the operation, :samp:`{old}` contains the value just before the operation, + which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the ``value`` to + the atomic integer variable or does a bitwise AND, OR or exclusive OR + between the atomic variable and :samp:`{value}` ; the result is then stored in the + atomic variable. + + :param op: + intent(in) the operation to be performed; possible values + ``GFC_CAF_ATOMIC_ADD`` (1), ``GFC_CAF_ATOMIC_AND`` (2), + ``GFC_CAF_ATOMIC_OR`` (3), ``GFC_CAF_ATOMIC_XOR`` (4). + + :param token: + intent(in) An opaque pointer identifying the coarray. + + :param offset: + intent(in) By which amount of bytes the actual data is + shifted compared to the base address of the coarray. + + :param image_index: + intent(in) The ID of the remote image; must be a + positive number; zero indicates the current image when used noncoindexed. + + :param old: + intent(out) The value which the atomic variable had + just before the atomic operation. + + :param val: + intent(in) The new value for the atomic variable, + assigned to the atomic variable, if ``compare`` equals the value of the + atomic variable. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param type: + intent(in) the data type, i.e. ``BT_INTEGER`` (1) or + ``BT_LOGICAL`` (2) + + :param kind: + intent(in) the kind value (only 4; always ``int``) + +.. index:: Coarray, _gfortran_caf_co_broadcast + +.. _gfortran_caf_co_broadcast: + +_gfortran_caf_co_broadcast --- Sending data to all images +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_co_broadcast (gfc_descriptor_t *a, int source_image, int *stat, char *errmsg, size_t errmsg_len) + + Distribute a value from a given image to all other images in the team. Has to + be called collectively. + + :param a: + intent(inout) An array descriptor with the data to be + broadcasted (on :samp:`{source_image}`) or to be received (other images). + + :param source_image: + intent(in) The ID of the image from which the + data should be broadcasted. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param errmsg_len: + intent(in) the buffer size of errmsg. + +.. index:: Coarray, _gfortran_caf_co_max + +.. _gfortran_caf_co_max: + +_gfortran_caf_co_max --- Collective maximum reduction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_co_max (gfc_descriptor_t *a, int result_image, int *stat, char *errmsg, int a_len, size_t errmsg_len) + + Calculates for each array element of the variable :samp:`{a}` the maximum + value for that element in the current team; if :samp:`{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. + + :param a: + intent(inout) An array descriptor for the data to be + processed. On the destination image(s) the result overwrites the old content. + + :param result_image: + 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. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param a_len: + intent(in) the string length of argument :samp:`{a}` + + :param errmsg_len: + intent(in) the buffer size of errmsg + + .. note:: + + If :samp:`{result_image}` is nonzero, the data in the array descriptor :samp:`{a}` on + all images except of the specified one become undefined; hence, the library may + make use of this. + +.. index:: Coarray, _gfortran_caf_co_min + +.. _gfortran_caf_co_min: + +_gfortran_caf_co_min --- Collective minimum reduction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_co_min (gfc_descriptor_t *a, int result_image, int *stat, char *errmsg, int a_len, size_t errmsg_len) + + Calculates for each array element of the variable :samp:`{a}` the minimum + value for that element in the current team; if :samp:`{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. + + :param a: + intent(inout) An array descriptor for the data to be + processed. On the destination image(s) the result overwrites the old content. + + :param result_image: + 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. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param a_len: + intent(in) the string length of argument :samp:`{a}` + + :param errmsg_len: + intent(in) the buffer size of errmsg + + .. note:: + + If :samp:`{result_image}` is nonzero, the data in the array descriptor :samp:`{a}` on + all images except of the specified one become undefined; hence, the library may + make use of this. + +.. index:: Coarray, _gfortran_caf_co_sum + +.. _gfortran_caf_co_sum: + +_gfortran_caf_co_sum --- Collective summing reduction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_caf_co_sum (gfc_descriptor_t *a, int result_image, int *stat, char *errmsg, size_t errmsg_len) + + Calculates for each array element of the variable :samp:`{a}` the sum of all + values for that element in the current team; if :samp:`{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. + + :param a: + intent(inout) An array descriptor with the data to be + processed. On the destination image(s) the result overwrites the old content. + + :param result_image: + 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. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param errmsg_len: + intent(in) the buffer size of errmsg + + .. note:: + + If :samp:`{result_image}` is nonzero, the data in the array descriptor :samp:`{a}` on + all images except of the specified one become undefined; hence, the library may + make use of this. + +.. index:: Coarray, _gfortran_caf_co_reduce + +.. _gfortran_caf_co_reduce: + +_gfortran_caf_co_reduce --- Generic collective reduction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: 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) + + Calculates for each array element of the variable :samp:`{a}` the reduction + value for that element in the current team; if :samp:`{result_image}` has the + value 0, the result shall be stored on all images, otherwise, only on the + specified image. The :samp:`{opr}` is a pure function doing a mathematically + commutative and associative operation. + + :param a: + intent(inout) An array descriptor with the data to be + processed. On the destination image(s) the result overwrites the old content. + + :param opr: + intent(in) Function pointer to the reduction function + + :param opr_flags: + intent(in) Flags regarding the reduction function + + :param result_image: + 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. + + :param stat: + intent(out) Stores the status STAT= and may be NULL. + + :param errmsg: + intent(out) When an error occurs, this will be set to + an error message; may be NULL. + + :param a_len: + intent(in) the string length of argument :samp:`{a}` + + :param errmsg_len: + intent(in) the buffer size of errmsg + + .. note:: + + If :samp:`{result_image}` is nonzero, the data in the array descriptor :samp:`{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. + +.. Intrinsic Procedures + - + +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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/funding.rst b/gcc/fortran/doc/gfortran/funding.rst new file mode 100644 index 0000000..2d76ad9 --- /dev/null +++ b/gcc/fortran/doc/gfortran/funding.rst @@ -0,0 +1,6 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. include:: ../../../../doc/funding.rst
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/general-public-license-3.rst b/gcc/fortran/doc/gfortran/general-public-license-3.rst new file mode 100644 index 0000000..cfca1c3 --- /dev/null +++ b/gcc/fortran/doc/gfortran/general-public-license-3.rst @@ -0,0 +1,6 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. include:: ../../../../doc/gpl-3.0.rst
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-and-gcc.rst b/gcc/fortran/doc/gfortran/gnu-fortran-and-gcc.rst new file mode 100644 index 0000000..2ec86fb --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-and-gcc.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GNU Compiler Collection, GCC + +.. _gnu-fortran-and-gcc: + +GNU Fortran and 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 :samp:`.f`, :samp:`.for`, :samp:`.ftn`, +:samp:`.f90`, :samp:`.f95`, :samp:`.f03` and :samp:`.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 :samp:`.f`, :samp:`.for`, :samp:`.fpp`, :samp:`.ftn`, :samp:`.F`, +:samp:`.FOR`, :samp:`.FPP`, and :samp:`.FTN` extensions are treated as fixed form. +Source files with :samp:`.f90`, :samp:`.f95`, :samp:`.f03`, :samp:`.f08`, +:samp:`.F90`, :samp:`.F95`, :samp:`.F03` and :samp:`.F08` extensions are +treated as free form. The capitalized versions of either form are run +through preprocessing. Source files with the lower case :samp:`.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 +which relate to the optimization passes and the back-end code generation +that relate to the optimization passes and the back-end code generation +are documented in the GCC manual; see :ref:`gcc:top`. +The two manuals together provide a complete reference for the GNU +Fortran compiler.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options.rst new file mode 100644 index 0000000..880b34c --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options.rst @@ -0,0 +1,33 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GNU Fortran command options, command options, options, gfortran command + +GNU Fortran Command Options +--------------------------- + +.. _invoking-gnu-fortran: + +.. toctree:: + :maxdepth: 2 + + gnu-fortran-command-options/description + gnu-fortran-command-options/option-summary + gnu-fortran-command-options/options-controlling-fortran-dialect + gnu-fortran-command-options/enable-and-customize-preprocessing + gnu-fortran-command-options/options-to-request-or-suppress-errors-and-warnings + gnu-fortran-command-options/options-for-debugging-your-program-or-gnu-fortran + gnu-fortran-command-options/options-for-directory-search + gnu-fortran-command-options/influencing-the-linking-step + gnu-fortran-command-options/influencing-runtime-behavior + gnu-fortran-command-options/options-for-code-generation-conventions + gnu-fortran-command-options/options-for-interoperability-with-other-languages + gnu-fortran-command-options/environment-variables-affecting-gfortran + +.. only:: man + + .. toctree:: + + copyright
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/description.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/description.rst new file mode 100644 index 0000000..c0f0594 --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/description.rst @@ -0,0 +1,39 @@ +.. only:: man + + Synopsis + ^^^^^^^^ + + gfortran [ :option:`-c` | :option:`-S` | :option:`-E` ] + [ :option:`-g` ] [ :option:`-pg` ] [ :option:`-O`:samp:`{level}` ] + [ :option:`-W`:samp:`{warn}`...] [ :option:`-pedantic` ] + [ :option:`-I`:samp:`{dir}`...] [ :option:`-L`:samp:`{dir}`...] + [ :option:`-D`:samp:`{macro}` [= :samp:`{defn}` ]...] [ :option:`-U`:samp:`{macro}` ] + [ :option:`-f`:samp:`{option}`...] + [ :option:`-m`:samp:`{machine-option}`...] + [ :option:`-o` :samp:`{outfile}` ] :samp:`{infile}`... + +Description +^^^^^^^^^^^ + +The :command:`gfortran` command supports all the options supported by the +:command:`gcc` command. Only options specific to GNU Fortran are documented +here. + +See :ref:`gcc:invoking-gcc`, for information +on the non-Fortran-specific aspects of the :command:`gcc` command (and, +therefore, the :command:`gfortran` command). + +.. index:: 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 :samp:`-ffoo` would be :samp:`-fno-foo`. +This manual documents only one of these two forms, whichever +one is not the default.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/enable-and-customize-preprocessing.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/enable-and-customize-preprocessing.rst new file mode 100644 index 0000000..0db92c6 --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/enable-and-customize-preprocessing.rst @@ -0,0 +1,298 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: preprocessor, options, preprocessor, CPP, FPP, Conditional compilation, Preprocessing, preprocessor, include file handling + +.. _preprocessing-options: + +Enable and customize preprocessing +********************************** + +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 :samp:`.F`, :samp:`.FOR`, :samp:`.FTN`, :samp:`.fpp`, +:samp:`.FPP`, :samp:`.F90`, :samp:`.F95`, :samp:`.F03` or :samp:`.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 ``INCLUDE`` +statement, the included file is not preprocessed. To preprocess included +files, use the equivalent preprocessor statement ``#include``. + +If GNU Fortran invokes the preprocessor, ``__GFORTRAN__`` +is defined. The macros ``__GNUC__``, ``__GNUC_MINOR__`` and +``__GNUC_PATCHLEVEL__`` can be used to determine the version of the +compiler. See :ref:`cpp:top` for details. + +GNU Fortran supports a number of ``INTEGER`` and ``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: ``__GFC_INT_1__``, +``__GFC_INT_2__``, ``__GFC_INT_8__``, ``__GFC_INT_16__``, +``__GFC_REAL_10__``, and ``__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 (http://www.daniellnagle.com/coco.html). + +The following options control preprocessing of Fortran code: + +.. index:: cpp, fpp, preprocessor, enable, preprocessor, disable + +.. option:: -cpp, -nocpp + + Enable preprocessing. The preprocessor is automatically invoked if + the file extension is :samp:`.fpp`, :samp:`.FPP`, :samp:`.F`, :samp:`.FOR`, + :samp:`.FTN`, :samp:`.F90`, :samp:`.F95`, :samp:`.F03` or :samp:`.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. + +.. index:: dM, preprocessor, debugging, debugging, preprocessor + +.. option:: -dM + + Instead of the normal output, generate a list of ``'#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 :samp:`foo.f90`, the command + + .. code-block:: bash + + touch foo.f90; gfortran -cpp -E -dM foo.f90 + + will show all the predefined macros. + +.. index:: dD, preprocessor, debugging, debugging, preprocessor + +.. option:: -dD + + Like :option:`-dM` except in two respects: it does not include the + predefined macros, and it outputs both the ``#define`` directives + and the result of preprocessing. Both kinds of output go to the + standard output file. + +.. index:: dN, preprocessor, debugging, debugging, preprocessor + +.. option:: -dN + + Like :option:`-dD`, but emit only the macro names, not their expansions. + +.. index:: dU, preprocessor, debugging, debugging, preprocessor + +.. option:: -dU + + Like 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 ``'#undef'`` + directives are also output for macros tested but undefined at the time. + +.. index:: dI, preprocessor, debugging, debugging, preprocessor + +.. option:: -dI + + Output ``'#include'`` directives in addition to the result + of preprocessing. + +.. index:: fworking-directory, preprocessor, working directory + +.. option:: -fworking-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 ``#line`` + directives are emitted whatsoever. + +.. index:: idirafter dir, preprocessing, include path + +.. option:: -idirafter {dir} + + Search :samp:`{dir}` for include files, but do it after all directories + specified with :option:`-I` and the standard system directories have + been exhausted. :samp:`{dir}` is treated as a system include directory. + If dir begins with ``=``, then the ``=`` will be replaced by + the sysroot prefix; see :option:`--sysroot` and :option:`-isysroot`. + +.. index:: imultilib dir, preprocessing, include path + +.. option:: -imultilib {dir} + + Use :samp:`{dir}` as a subdirectory of the directory containing target-specific + C++ headers. + +.. index:: iprefix prefix, preprocessing, include path + +.. option:: -iprefix {prefix} + + Specify :samp:`{prefix}` as the prefix for subsequent :option:`-iwithprefix` + options. If the :samp:`{prefix}` represents a directory, you should include + the final ``'/'``. + +.. index:: isysroot dir, preprocessing, include path + +.. option:: -isysroot {dir} + + This option is like the :option:`--sysroot` option, but applies only to + header files. See the :option:`--sysroot` option for more information. + +.. index:: iquote dir, preprocessing, include path + +.. option:: -iquote {dir} + + Search :samp:`{dir}` only for header files requested with ``#include "file"`` ; + they are not searched for ``#include <file>``, before all directories + specified by :option:`-I` and before the standard system directories. If + :samp:`{dir}` begins with ``=``, then the ``=`` will be replaced by the + sysroot prefix; see :option:`--sysroot` and :option:`-isysroot`. + +.. index:: isystem dir, preprocessing, include path + +.. option:: -isystem {dir} + + Search :samp:`{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 :samp:`{dir}` begins with + ``=``, then the ``=`` will be replaced by the sysroot prefix; + see :option:`--sysroot` and :option:`-isysroot`. + +.. index:: nostdinc + +.. option:: -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. + +.. index:: undef + +.. option:: -undef + + Do not predefine any system-specific or GCC-specific macros. + The standard predefined macros remain defined. + +.. index:: Apredicate=answer, preprocessing, assertion + +.. option:: -Apredicate={answer} + + Make an assertion with the predicate :samp:`{predicate}` and answer :samp:`{answer}`. + This form is preferred to the older form -A predicate(answer), which is still + supported, because it does not use shell special characters. + +.. index:: A-predicate=answer, preprocessing, assertion + +.. option:: -A-predicate={answer} + + Cancel an assertion with the predicate :samp:`{predicate}` and answer :samp:`{answer}`. + +.. index:: C, preprocessing, keep comments + +.. option:: -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 ``'#'``. + + Warning: this currently handles C-Style comments only. The preprocessor + does not yet recognize Fortran-style comments. + +.. index:: CC, preprocessing, keep comments + +.. option:: -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. + + Warning: this currently handles C- and C++-Style comments only. The + preprocessor does not yet recognize Fortran-style comments. + +.. index:: Dname, preprocessing, define macros + +.. option:: -Dname + + Predefine name as a macro, with definition ``1``. + +.. index:: Dname=definition, preprocessing, define macros + +.. option:: -Dname={definition} + + The contents of :samp:`{definition}` are tokenized and processed as if they + appeared during translation phase three in a ``'#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, ``-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. + +.. index:: H + +.. option:: -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 ``'#include'`` + stack it is. + +.. index:: P, preprocessing, no linemarkers + +.. option:: -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. + +.. index:: Uname, preprocessing, undefine macros + +.. option:: -Uname + + Cancel any previous definition of :samp:`{name}`, either built in or provided + with a :option:`-D` option.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/environment-variables-affecting-gfortran.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/environment-variables-affecting-gfortran.rst new file mode 100644 index 0000000..cd6af4c --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/environment-variables-affecting-gfortran.rst @@ -0,0 +1,24 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: environment variable + +.. _environment-variables: + +Environment variables affecting gfortran +**************************************** + +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`. + +See :ref:`gcc:environment-variables`, for information on environment +variables. + +See :ref:`runtime`, for environment variables that affect the +run-time behavior of programs compiled with GNU Fortran.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/influencing-runtime-behavior.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/influencing-runtime-behavior.rst new file mode 100644 index 0000000..08f0558 --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/influencing-runtime-behavior.rst @@ -0,0 +1,67 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: options, runtime + +.. _runtime-options: + +Influencing runtime behavior +**************************** + +These options affect the runtime behavior of programs compiled with GNU Fortran. + +.. index:: fconvert=conversion + +.. option:: -fconvert={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 + + * :option:`-fconvert=r16_ieee` Use IEEE 128-bit format for + ``REAL(KIND=16)``. + + * :option:`-fconvert=r16_ibm` Use IBM long double format for + ``REAL(KIND=16)``. + + This option has an effect only when used in the main program. + The ``CONVERT`` specifier and the GFORTRAN_CONVERT_UNIT environment + variable override the default specified by :option:`-fconvert`. + +.. index:: frecord-marker=length + +.. option:: -frecord-marker={length} + + Specify the length of record markers for unformatted files. + Valid values for :samp:`{length}` are 4 and 8. Default is 4. + 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`. + +.. index:: fmax-subrecord-length=length + +.. option:: -fmax-subrecord-length={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. + +.. index:: fsign-zero + +.. option:: -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 ``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 ``SIGN`` intrinsic for + compatibility with Fortran 77. The default is :option:`-fsign-zero`.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/influencing-the-linking-step.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/influencing-the-linking-step.rst new file mode 100644 index 0000000..2e9e39f --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/influencing-the-linking-step.rst @@ -0,0 +1,37 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: options, linking, linking, static + +.. _link-options: + +Influencing the linking step +**************************** + +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. + +.. index:: static-libgfortran + +.. option:: -static-libgfortran + + On systems that provide :samp:`libgfortran` as a shared and a static + library, this option forces the use of the static version. If no + shared version of :samp:`libgfortran` was built when the compiler was + configured, this option has no effect. + +.. index:: static-libquadmath + +.. option:: -static-libquadmath + + On systems that provide :samp:`libquadmath` as a shared and a static + library, this option forces the use of the static version. If no + shared version of :samp:`libquadmath` was built when the compiler was + configured, this option has no effect. + + Please note that the :samp:`libquadmath` runtime library is licensed under the + GNU Lesser General Public License (LGPL), and linking it statically introduces + requirements when redistributing the resulting binaries.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/option-summary.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/option-summary.rst new file mode 100644 index 0000000..7e69d40 --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/option-summary.rst @@ -0,0 +1,104 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _option-summary: + +Option summary +************** + +Options +^^^^^^^ + +Here is a summary of all the options specific to GNU Fortran, grouped +by type. Explanations are in the following sections. + +*Fortran Language Options* + See :ref:`fortran-dialect-options`. + + :option:`-fall-intrinsics` :option:`-fallow-argument-mismatch` :option:`-fallow-invalid-boz` |gol| + :option:`-fbackslash` :option:`-fcray-pointer` :option:`-fd-lines-as-code` :option:`-fd-lines-as-comments` |gol| + :option:`-fdec` :option:`-fdec-char-conversions` :option:`-fdec-structure` :option:`-fdec-intrinsic-ints` |gol| + :option:`-fdec-static` :option:`-fdec-math` :option:`-fdec-include` :option:`-fdec-format-defaults` |gol| + :option:`-fdec-blank-format-item` :option:`-fdefault-double-8` :option:`-fdefault-integer-8` |gol| + :option:`-fdefault-real-8` :option:`-fdefault-real-10` :option:`-fdefault-real-16` :option:`-fdollar-ok` |gol| + :option:`-ffixed-line-length-n` :option:`-ffixed-line-length-none` :option:`-fpad-source` |gol| + :option:`-ffree-form` :option:`-ffree-line-length-n` :option:`-ffree-line-length-none` |gol| + :option:`-fimplicit-none` :option:`-finteger-4-integer-8` :option:`-fmax-identifier-length` |gol| + :option:`-fmodule-private` :option:`-ffixed-form` :option:`-fno-range-check` :option:`-fopenacc` :option:`-fopenmp` |gol| + :option:`-freal-4-real-10` :option:`-freal-4-real-16` :option:`-freal-4-real-8` :option:`-freal-8-real-10` |gol| + :option:`-freal-8-real-16` :option:`-freal-8-real-4` :option:`-std=std` :option:`-ftest-forall-temp` + +*Preprocessing Options* + See :ref:`preprocessing-options`. + + :option:`-A-question[=answer]` |gol| + :option:`-Aquestion` = :samp:`{answer}` :option:`-C` :option:`-CC` :option:`-Dmacro[=defn]` |gol| + :option:`-H` :option:`-P` |gol| + :option:`-Umacro` :option:`-cpp` :option:`-dD` :option:`-dI` :option:`-dM` :option:`-dN` :option:`-dU` :option:`-fworking-directory`|gol| + :option:`-imultilib` :samp:`{dir}` |gol| + :option:`-iprefix` :samp:`{file}` :option:`-iquote` :option:`-isysroot` :samp:`{dir}` :option:`-isystem` :samp:`{dir}` :option:`-nocpp` |gol| + :option:`-nostdinc` |gol| + :option:`-undef` + +*Error and Warning Options* + See :ref:`error-and-warning-options`. + + :option:`-Waliasing` :option:`-Wall` :option:`-Wampersand` :option:`-Warray-bounds` |gol| + :option:`-Wc-binding-type` :option:`-Wcharacter-truncation` :option:`-Wconversion` |gol| + :option:`-Wdo-subscript` :option:`-Wfunction-elimination` :option:`-Wimplicit-interface` |gol| + :option:`-Wimplicit-procedure` :option:`-Wintrinsic-shadow` :option:`-Wuse-without-only` |gol| + :option:`-Wintrinsics-std` :option:`-Wline-truncation` :option:`-Wno-align-commons` |gol| + :option:`-Wno-overwrite-recursive` :option:`-Wno-tabs` :option:`-Wreal-q-constant` :option:`-Wsurprising` |gol| + :option:`-Wunderflow` :option:`-Wunused-parameter` :option:`-Wrealloc-lhs` :option:`-Wrealloc-lhs-all` |gol| + :option:`-Wfrontend-loop-interchange` :option:`-Wtarget-lifetime` :option:`-fmax-errors=n` |gol| + :option:`-fsyntax-only` :option:`-pedantic` |gol| + :option:`-pedantic-errors` + +*Debugging Options* + See :ref:`debugging-options`. + + :option:`-fbacktrace` :option:`-fdump-fortran-optimized` :option:`-fdump-fortran-original` |gol| + :option:`-fdebug-aux-vars` :option:`-fdump-fortran-global` :option:`-fdump-parse-tree` :option:`-ffpe-trap=list` |gol| + :option:`-ffpe-summary=list` + +*Directory Options* + See :ref:`directory-options`. + + :option:`-Idir` :option:`-Jdir` :option:`-fintrinsic-modules-path` :samp:`{dir}` + +*Link Options* + See :ref:`link-options`. + + :option:`-static-libgfortran` :option:`-static-libquadmath` + +*Runtime Options* + See :ref:`runtime-options`. + + :option:`-fconvert=conversion` :option:`-fmax-subrecord-length=length` |gol| + :option:`-frecord-marker=length` :option:`-fsign-zero` + +*Interoperability Options* + See :ref:`interoperability-options`. + + :option:`-fc-prototypes` :option:`-fc-prototypes-external` + +*Code Generation Options* + See :ref:`code-gen-options`. + + :option:`-faggressive-function-elimination` :option:`-fblas-matmul-limit=n` |gol| + :option:`-fbounds-check` :option:`-ftail-call-workaround` :option:`-ftail-call-workaround=n` |gol| + :option:`-fcheck-array-temporaries` |gol| + :option:`-fcheck=<all|array-temps|bits|bounds|do|mem|pointer|recursion>` |gol| + :option:`-fcoarray=<none|single|lib>` :option:`-fexternal-blas` :option:`-ff2c` |gol| + :option:`-ffrontend-loop-interchange` :option:`-ffrontend-optimize` |gol| + :option:`-finit-character=n` :option:`-finit-integer=n` :option:`-finit-local-zero` |gol| + :option:`-finit-derived` :option:`-finit-logical=<true|false>` |gol| + :option:`-finit-real=<zero|inf|-inf|nan|snan>`|gol| + :option:`-finline-matmul-limit=n` |gol| + :option:`-finline-arg-packing` :option:`-fmax-array-constructor=n` |gol| + :option:`-fmax-stack-var-size=n` :option:`-fno-align-commons` :option:`-fno-automatic` |gol| + :option:`-fno-protect-parens` :option:`-fno-underscoring` :option:`-fsecond-underscore` |gol| + :option:`-fpack-derived` :option:`-frealloc-lhs` :option:`-frecursive` :option:`-frepack-arrays` |gol| + :option:`-fshort-enums` :option:`-fstack-arrays`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-controlling-fortran-dialect.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-controlling-fortran-dialect.rst new file mode 100644 index 0000000..175f925 --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-controlling-fortran-dialect.rst @@ -0,0 +1,411 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: dialect options, language, dialect options, options, dialect + +.. _fortran-dialect-options: + +Options controlling Fortran dialect +*********************************** + +The following options control the details of the Fortran dialect +accepted by the compiler: + +.. index:: ffree-form, ffixed-form, options, Fortran dialect, file format, free, file format, fixed + +.. option:: -ffree-form, -ffixed-form + + 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. + +.. index:: fall-intrinsics + +.. option:: -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 ``EXTERNAL``. + +.. index:: fallow-argument-mismatch + +.. option:: -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 *strongly* discouraged. It is possible to + provide standard-conforming code which allows different types of + arguments by using an explicit interface and ``TYPE(*)``. + +.. index:: allow-invalid-boz + +.. option:: -fallow-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. + +.. index:: fd-lines-as-code, fd-lines-as-comments + +.. option:: -fd-lines-as-code, -fd-lines-as-comments + + Enable special treatment for lines beginning with ``d`` or ``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. + +.. index:: fdec + +.. option:: -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` |gol| + :option:`-fdec-structure` :option:`-fdec-intrinsic-ints` :option:`-fdec-static` |gol| + :option:`-fdec-math` :option:`-fdec-include` :option:`-fdec-blank-format-item` |gol| + :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`. + +.. index:: fdec-char-conversions + +.. option:: -fdec-char-conversions + + Enable the use of character literals in assignments and ``DATA`` statements + for non-character variables. + +.. index:: fdec-structure + +.. option:: -fdec-structure + + Enable DEC ``STRUCTURE`` and ``RECORD`` as well as ``UNION``, + ``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. + +.. index:: fdec-intrinsic-ints + +.. option:: -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. + +.. index:: fdec-math + +.. option:: -fdec-math + + Enable legacy math intrinsics such as COTAN and degree-valued trigonometric + functions (e.g. TAND, ATAND, etc...) for compatability with older code. + +.. index:: fdec-static + +.. option:: -fdec-static + + Enable DEC-style STATIC and AUTOMATIC attributes to explicitly specify + the storage of variables and other objects. + +.. index:: fdec-include + +.. option:: -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. + +.. index:: fdec-format-defaults + +.. option:: -fdec-format-defaults + + Enable format specifiers F, G and I to be used without width specifiers, + default widths will be used instead. + +.. index:: fdec-blank-format-item + +.. option:: -fdec-blank-format-item + + Enable a blank format item at the end of a format specification i.e. nothing + following the final comma. + +.. index:: fdollar-ok, $, symbol names, character set + +.. option:: -fdollar-ok + + 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 ``IMPLICIT`` statements is also rejected. + +.. index:: backslash, backslash, escape characters + +.. option:: -fbackslash + + Change the interpretation of backslashes in string literals from a single + backslash character to 'C-style' escape characters. The following + combinations are expanded ``\a``, ``\b``, ``\f``, ``\n``, + ``\r``, ``\t``, ``\v``, ``\\``, and ``\0`` to the ASCII + characters alert, backspace, form feed, newline, carriage return, + horizontal tab, vertical tab, backslash, and NUL, respectively. + Additionally, ``\x``:samp:`{nn}`, ``\u``:samp:`{nnnn}` and + ``\U``:samp:`{nnnnnnnn}` (where each :samp:`{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. + +.. index:: fmodule-private, module entities, private + +.. option:: -fmodule-private + + Set the default accessibility of module entities to ``PRIVATE``. + Use-associated entities will not be accessible unless they are explicitly + declared as ``PUBLIC``. + +.. index:: ffixed-line-length-n, file format, fixed + +.. option:: -ffixed-line-length-n + -ffixed-line-length-none + -ffixed-line-length-0 + + Set column after which characters are ignored in typical fixed-form + lines in the source file, and, unless ``-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 :samp:`{n}` include 72 (the + standard and the default), 80 (card image), and 132 (corresponding + to 'extended-source' options in some popular compilers). + :samp:`{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`. + +.. index:: fpad-source + +.. option:: -fno-pad-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. + +.. index:: ffree-line-length-n, file format, free + +.. option:: -ffree-line-length-n + -ffree-line-length-none + -ffree-line-length-0 + + Set column after which characters are ignored in typical free-form + lines in the source file. The default value is 132. + :samp:`{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`. + +.. index:: fmax-identifier-length=n + +.. option:: -fmax-identifier-length={n} + + Specify the maximum allowed identifier length. Typical values are + 31 (Fortran 95) and 63 (Fortran 2003 and later). + +.. index:: fimplicit-none + +.. option:: -fimplicit-none + + Specify that no implicit typing is allowed, unless overridden by explicit + ``IMPLICIT`` statements. This is the equivalent of adding + ``implicit none`` to the start of every procedure. + +.. index:: fcray-pointer + +.. option:: -fcray-pointer + + Enable the Cray pointer extension, which provides C-like pointer + functionality. + +.. index:: fopenacc, OpenACC + +.. option:: -fopenacc + + Enable the OpenACC extensions. This includes OpenACC ``!$acc`` + directives in free form and ``c$acc``, ``*$acc`` and + ``!$acc`` directives in fixed form, ``!$`` conditional + compilation sentinels in free form and ``c$``, ``*$`` and + ``!$`` sentinels in fixed form, and when linking arranges for the + OpenACC runtime library to be linked in. + +.. index:: fopenmp, OpenMP + +.. option:: -fopenmp + + Enable the OpenMP extensions. This includes OpenMP ``!$omp`` directives + in free form + and ``c$omp``, ``*$omp`` and ``!$omp`` directives in fixed form, + ``!$`` conditional compilation sentinels in free form + and ``c$``, ``*$`` and ``!$`` sentinels in fixed form, + and when linking arranges for the OpenMP runtime library to be linked + in. The option :option:`-fopenmp` implies :option:`-frecursive`. + +.. index:: frange-check + +.. option:: -fno-range-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 ``a = 1. / 0``. + With this option, no error will be given and ``a`` will be assigned + the value ``+Infinity``. If an expression evaluates to a value + outside of the relevant range of [ ``-HUGE()`` : ``HUGE()`` ], + then the expression will be replaced by ``-Inf`` or ``+Inf`` + as appropriate. + Similarly, ``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 ``i`` will be initialized to -1 instead. + +.. index:: fdefault-integer-8 + +.. option:: -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 ``42``. Unlike + :option:`-finteger-4-integer-8`, it does not promote variables with explicit + kind declaration. + +.. index:: fdefault-real-8 + +.. option:: -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 ``1.0``. This option promotes + the default width of ``DOUBLE PRECISION`` and double real constants + like ``1.d0`` to 16 bytes if possible. If ``-fdefault-double-8`` + is given along with ``fdefault-real-8``, ``DOUBLE PRECISION`` + and double real constants are not promoted. Unlike :option:`-freal-4-real-8`, + ``fdefault-real-8`` does not promote variables with explicit kind + declarations. + +.. index:: fdefault-real-10 + +.. option:: -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 ``1.0``. This option promotes + the default width of ``DOUBLE PRECISION`` and double real constants + like ``1.d0`` to 16 bytes if possible. If ``-fdefault-double-8`` + is given along with ``fdefault-real-10``, ``DOUBLE PRECISION`` + and double real constants are not promoted. Unlike :option:`-freal-4-real-10`, + ``fdefault-real-10`` does not promote variables with explicit kind + declarations. + +.. index:: fdefault-real-16 + +.. option:: -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 ``1.0``. This option promotes + the default width of ``DOUBLE PRECISION`` and double real constants + like ``1.d0`` to 16 bytes if possible. If ``-fdefault-double-8`` + is given along with ``fdefault-real-16``, ``DOUBLE PRECISION`` + and double real constants are not promoted. Unlike :option:`-freal-4-real-16`, + ``fdefault-real-16`` does not promote variables with explicit kind + declarations. + +.. index:: fdefault-double-8 + +.. option:: -fdefault-double-8 + + Set the ``DOUBLE PRECISION`` type and double real constants + like ``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 ``DOUBLE PRECISION`` and double real constants like + ``1.d0`` to 16 bytes. + +.. index:: finteger-4-integer-8 + +.. option:: -finteger-4-integer-8 + + Promote all ``INTEGER(KIND=4)`` entities to an ``INTEGER(KIND=8)`` + entities. If ``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 ``EQUIVALENCE`` and/or ``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. + +.. index:: freal-4-real-8, freal-4-real-10, freal-4-real-16, freal-8-real-4, freal-8-real-10, freal-8-real-16, options, real kind type promotion + +.. option:: -freal-4-real-8, -freal-4-real-10, -freal-4-real-16, -freal-8-real-4, -freal-8-real-10, -freal-8-real-16 + + Promote all ``REAL(KIND=M)`` entities to ``REAL(KIND=N)`` entities. + If ``REAL(KIND=N)`` is unavailable, then an error will be issued. + The ``-freal-4-`` flags also affect the default real kind and the + ``-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, ``-fdefault-real-8``, ``-fdefault-real-10``, + ``-fdefault-real-10``, and ``-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 ``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 ``EQUIVALENCE`` and/or ``COMMON``, generic interfaces, + BOZ literal constant conversion, and I/O and calls to intrinsic procedures + when passing a value to the ``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. + +.. index:: std=std option + +.. option:: -std={std} + + 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 + :samp:`{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. + +.. index:: ftest-forall-temp + +.. option:: -ftest-forall-temp + + Enhance test coverage by forcing most forall assignments to use temporary.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-code-generation-conventions.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-code-generation-conventions.rst new file mode 100644 index 0000000..f83846a --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-code-generation-conventions.rst @@ -0,0 +1,583 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: code generation, conventions, options, code generation, options, run-time + +.. _code-gen-options: + +Options for code generation conventions +*************************************** + +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 :samp:`-ffoo` would be :samp:`-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 no- or adding +it. + +.. index:: fno-automatic, SAVE statement, statement, SAVE + +.. option:: -fno-automatic + + Treat each program unit (except those marked as RECURSIVE) as if the + ``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 ``SAVE`` attribute are + silently ignored unless the :option:`-pedantic` option is added. + +.. index:: calling convention, f2c calling convention, g77 calling convention, libf2c calling convention + +.. option:: -ff2c + + 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 ``REAL`` to actually return the C type ``double``, and + functions that return type ``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 ``REAL`` functions return the C type ``float``, and + ``COMPLEX`` functions return the GNU C type ``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. + + .. warning:: + + 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 ``COMPLEX`` or default ``REAL`` + functions between program parts which were compiled with different + calling conventions will break at execution time. + + .. warning:: + + This will break code which passes intrinsic functions + of type default ``REAL`` or ``COMPLEX`` as actual arguments, as + the library implementations use the :option:`-fno-f2c` calling conventions. + +.. index:: fno-underscoring, underscore, symbol names, underscores, transforming symbol names, symbol names, transforming + +.. option:: -fno-underscoring + + 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. + + .. warning:: + + 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-ā-vis existing libraries, tools, + and so on). + + For example, with :option:`-funderscoring`, and assuming that ``j()`` and + ``max_count()`` are external functions while ``my_var`` and + ``lvar`` are local variables, a statement like + + .. code-block:: fortran + + I = J() + MAX_COUNT (MY_VAR, LVAR) + + is implemented as something akin to: + + .. code-block:: fortran + + i = j_() + max_count__(&my_var__, &lvar); + + With :option:`-fno-underscoring`, the same statement is implemented as: + + .. code-block:: fortran + + i = j() + max_count(&my_var, &lvar); + + 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 *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. + +.. index:: fsecond-underscore, underscore, symbol names, underscores, transforming symbol names, symbol names, transforming, f2c calling convention, g77 calling convention, libf2c calling convention + +.. option:: -fsecond-underscore + + 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 ``MAX_COUNT`` + is implemented as a reference to the link-time external symbol + ``max_count__``, instead of ``max_count_``. This is required + for compatibility with :command:`g77` and :command:`f2c`, and is implied + by use of the :option:`-ff2c` option. + +.. index:: fcoarray, coarrays + +.. option:: -fcoarray={<keyword>} + + none + Disable coarray support; using coarray declarations and image-control + statements will produce a compile-time error. (Default) + + single + Single-image mode, i.e. ``num_images()`` is always one. + + lib + Library-based coarray parallelization; a suitable GNU Fortran coarray + library needs to be linked. + +.. index:: fcheck, array, bounds checking, bit intrinsics checking, bounds checking, pointer checking, memory checking, range checking, subscript checking, checking subscripts, run-time checking, checking array temporaries + +.. option:: -fcheck={<keyword>} + + Enable the generation of run-time checks; the argument shall be + a comma-delimited list of the following keywords. Prefixing a check with + no- disables it if it was activated by a previous specification. + + all + Enable all run-time test of :option:`-fcheck`. + + 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. + + bits + Enable generation of run-time checks for invalid arguments to the bit + manipulation intrinsics. + + 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. + + do + Enable generation of run-time checks for invalid modification of loop + iteration variables. + + mem + Enable generation of run-time checks for memory allocation. + Note: This option does not affect explicit allocations using the + ``ALLOCATE`` statement, which will be always checked. + + pointer + Enable generation of run-time checks for pointers and allocatables. + + 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`. + + Example: Assuming you have a file :samp:`foo.f90`, the command + + .. code-block:: bash + + gfortran -fcheck=all,no-array-temps foo.f90 + + will compile the file with all checks enabled as specified above except + warnings for generated array temporaries. + +.. index:: fbounds-check + +.. option:: -fbounds-check + + .. Note: This option is also referred in gcc's manpage + + Deprecated alias for :option:`-fcheck=bounds`. + +.. index:: tail-call-workaround + +.. option:: -ftail-call-workaround, -ftail-call-workaround={n} + + Some C interfaces to Fortran codes violate the gfortran ABI by + omitting the hidden character length arguments as described in + See :ref:`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 *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. + +.. index:: fcheck-array-temporaries + +.. option:: -fcheck-array-temporaries + + Deprecated alias for :option:`-fcheck=array-temps`. + +.. index:: fmax-array-constructor + +.. option:: -fmax-array-constructor={n} + + 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. + + .. code-block:: fortran + + 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 + + .. warning:: + This option can lead to long compile times and excessively + large object files. + + The default value for :samp:`{n}` is 65535. + +.. index:: fmax-stack-var-size + +.. option:: -fmax-stack-var-size={n} + + 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 :samp:`{n}` is 65536. + +.. index:: fstack-arrays + +.. option:: -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. + +.. index:: fpack-derived, structure packing + +.. option:: -fpack-derived + + 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. + +.. index:: frepack-arrays, repacking arrays + +.. option:: -frepack-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. + +.. index:: fshort-enums + +.. option:: -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 ``INTEGER`` kind a given + enumerator set will fit in, and give all its enumerators this kind. + +.. index:: finline-arg-packing + +.. option:: -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 ``foo`` in + + .. code-block:: fortran + + subroutine foo(a) + real, dimension(*) :: a + end subroutine foo + subroutine bar(b) + real, dimension(:) :: b + call foo(b) + end subroutine bar + + 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`. + +.. index:: fexternal-blas + +.. option:: -fexternal-blas + + This option will make :command:`gfortran` generate calls to BLAS functions + for some matrix operations like ``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. + +.. index:: fblas-matmul-limit + +.. option:: -fblas-matmul-limit={n} + + Only significant when :option:`-fexternal-blas` is in effect. + Matrix multiplication of matrices with size larger than (or equal to) :samp:`{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 :samp:`{n}` is 30. + +.. index:: finline-matmul-limit + +.. option:: -finline-matmul-limit={n} + + When front-end optimization is active, some calls to the ``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 + ``-finline-matmul-limit=0`` will disable inlining in all cases. + Setting this option with a value of :samp:`{n}` will produce inline code + for matrices with size up to :samp:`{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 :samp:`{n}` is 30. The ``-fblas-matmul-limit`` + can be used to change this value. + +.. index:: frecursive + +.. option:: -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`. + +.. index:: finit-local-zero, finit-derived, finit-integer, finit-real, finit-logical, finit-character + +.. option:: -finit-local-zero + -finit-derived + -finit-integer={n} + -finit-real={<zero|inf|-inf|nan|snan>} + -finit-logical={<true|false>} + -finit-character={n} + + The :option:`-finit-local-zero` option instructs the compiler to + initialize local ``INTEGER``, ``REAL``, and ``COMPLEX`` + variables to zero, ``LOGICAL`` variables to false, and + ``CHARACTER`` variables to a string of null bytes. Finer-grained + initialization options are provided by the + :option:`-finit-integer=n`, + :option:`-finit-real=<zero|inf|-inf|nan|snan>` (which also initializes + the real and imaginary parts of local ``COMPLEX`` variables), + :option:`-finit-logical=<true|false>`, and + :option:`-finit-character=n` (where :samp:`{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 + + * objects with the POINTER attribute + + * allocatable arrays + + * variables that appear in an ``EQUIVALENCE`` statement. + + (These limitations may be removed in future releases). + + Note that the :option:`-finit-real=nan` option initializes ``REAL`` + and ``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 ``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. + +.. index:: falign-commons, alignment of COMMON blocks + +.. option:: -falign-commons + + By default, :command:`gfortran` enforces proper alignment of all variables in a + ``COMMON`` block by padding them as needed. On certain platforms this is mandatory, + on others it increases performance. If a ``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 ``COMMON`` block. + To avoid potential alignment issues in ``COMMON`` blocks, it is recommended to order + objects from largest to smallest. + +.. index:: fno-protect-parens, re-association of parenthesized expressions + +.. option:: -fno-protect-parens + + 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 ``REAL`` and + ``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. + +.. index:: frealloc-lhs, Reallocate the LHS in assignments + +.. option:: -frealloc-lhs + + 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`. + +.. index:: faggressive-function-elimination, Elimination of functions with identical argument lists + +.. option:: -faggressive-function-elimination + + Functions with identical argument lists are eliminated within + statements, regardless of whether these functions are marked + ``PURE`` or not. For example, in + + .. code-block:: fortran + + a = f(b,c) + f(b,c) + + there will only be a single call to ``f``. This option only works + if :option:`-ffrontend-optimize` is in effect. + +.. index:: frontend-optimize, Front-end optimization + +.. option:: -ffrontend-optimize + + 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: + + * inlining calls to ``MATMUL``, + + * elimination of identical function calls within expressions, + + * removing unnecessary calls to ``TRIM`` in comparisons and assignments, + + * replacing ``TRIM(a)`` with ``a(1:LEN_TRIM(a))`` and + + * short-circuiting of logical operators (``.AND.`` and ``.OR.``). + + It can be deselected by specifying :option:`-fno-frontend-optimize`. + +.. index:: frontend-loop-interchange, loop interchange, Fortran + +.. option:: -ffrontend-loop-interchange + + 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 ``FORALL`` and + ``DO CONCURRENT`` statements with several forall triplets. + +See :ref:`gcc:code-gen-options`, for information on more options +offered by the GBE +shared by :command:`gfortran`, :command:`gcc`, and other GNU compilers.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-debugging-your-program-or-gnu-fortran.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-debugging-your-program-or-gnu-fortran.rst new file mode 100644 index 0000000..d7ec72e --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-debugging-your-program-or-gnu-fortran.rst @@ -0,0 +1,134 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: options, debugging, debugging information options + +.. _debugging-options: + +Options for debugging your program or GNU Fortran +************************************************* + +GNU Fortran has various special options that are used for debugging +either your program or the GNU Fortran compiler. + +.. index:: fdump-fortran-original + +.. option:: -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. + +.. index:: fdump-fortran-optimized + +.. option:: -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. + +.. index:: fdump-parse-tree + +.. option:: -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 ``-fdump-fortran-original`` instead. + +.. index:: fdebug-aux-vars + +.. option:: -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 + ``-fdump-tree-original`` and enabling debugging of the executable + program by using ``-g`` or ``-ggdb3``. + +.. index:: fdump-fortran-global + +.. option:: -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. + +.. index:: ffpe-trap=list + +.. option:: -ffpe-trap={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. :samp:`{list}` + is a (possibly empty) comma-separated list of the following + exceptions: :samp:`invalid` (invalid floating point operation, such as + ``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: ' ``ffpe-trap=``:samp:`{list1}` ``ffpe-trap=``:samp:`{list2}` ' + is equivalent to ``ffpe-trap=``:samp:`{list1}`, :samp:`{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 ``ffpe-trap=inexact`` is likely to + be uninteresting in practice. + + By default no exception traps are enabled. + +.. index:: ffpe-summary=list + +.. option:: -ffpe-summary={list} + + Specify a list of floating-point exceptions, whose flag status is printed + to ``ERROR_UNIT`` when invoking ``STOP`` and ``ERROR STOP``. + :samp:`{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. + +.. index:: fno-backtrace, backtrace, trace + +.. option:: -fno-backtrace + + 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. ``-fno-backtrace`` disables the backtrace + generation. This option only has influence for compilation of the + Fortran main program. + +See :ref:`gcc:debugging-options`, for more information on +debugging options.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-directory-search.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-directory-search.rst new file mode 100644 index 0000000..a76f150 --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-directory-search.rst @@ -0,0 +1,54 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: directory, options, options, directory search, search path, INCLUDE directive, directive, INCLUDE + +.. _directory-options: + +Options for directory search +**************************** + +These options affect how GNU Fortran searches +for files specified by the ``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. + +.. index:: Idir, directory, search paths for inclusion, inclusion, directory search paths for, search paths, for included files, paths, search, module search path + +.. option:: -Idir + + These affect interpretation of the ``INCLUDE`` directive + (as well as of the ``#include`` directive of the :command:`cpp` + preprocessor). + + Also note that the general behavior of :option:`-I` and + ``INCLUDE`` is pretty much the same as of :option:`-I` with + ``#include`` in the :command:`cpp` preprocessor, with regard to + looking for :samp:`header.gcc` files and other such things. + + This path is also used to search for :samp:`.mod` files when previously + compiled modules are required by a ``USE`` statement. + + See :ref:`gcc:directory-options`, for information on the + :option:`-I` option. + +.. index:: Jdir, Mdir, paths, search, module search path + +.. option:: -Jdir + + This option specifies where to put :samp:`.mod` files for compiled modules. + It is also added to the list of directories to searched by an ``USE`` + statement. + + The default is the current directory. + +.. index:: fintrinsic-modules-pathdir, paths, search, module search path + +.. option:: -fintrinsic-modules-path {dir} + + This option specifies the location of pre-compiled intrinsic modules, if + they are not in the default location expected by the compiler.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-interoperability-with-other-languages.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-interoperability-with-other-languages.rst new file mode 100644 index 0000000..65f418c --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-for-interoperability-with-other-languages.rst @@ -0,0 +1,63 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _interoperability-options: + +Options for interoperability with other languages +************************************************* + +.. index:: c-prototypes, Generating C prototypes from Fortran BIND(C) enteties + +.. option:: -fc-prototypes + + This option will generate C prototypes from ``BIND(C)`` variable + declarations, types and procedure interfaces and writes them to + standard output. ``ENUM`` is not yet supported. + + The generated prototypes may need inclusion of an appropriate header, + such as ``<stdint.h>`` or ``<stdlib.h>``. For types which are + not specified using the appropriate kind from the ``iso_c_binding`` + module, a warning is added as a comment to the code. + + For function pointers, a pointer to a function returning ``int`` + without an explicit argument list is generated. + + Example of use: + + .. code-block:: shell-session + + $ gfortran -fc-prototypes -fsyntax-only foo.f90 > foo.h + + where the C code intended for interoperating with the Fortran code + then uses ``#include "foo.h"``. + +.. index:: c-prototypes-external, Generating C prototypes from external procedures + +.. option:: -fc-prototypes-external + + 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 ``BIND(C)`` procedures, use + :option:`-fc-prototypes` for that. + + The generated prototypes may need inclusion of an appropriate + header, such as ``<stdint.h>`` or ``<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 + ``BIND(C)`` features is recommended. + + Example of use: + + .. code-block:: shell-session + + $ gfortran -fc-prototypes-external -fsyntax-only foo.f > foo.h + + where the C code intended for interoperating with the Fortran code + then uses ``#include "foo.h"``.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-to-request-or-suppress-errors-and-warnings.rst b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-to-request-or-suppress-errors-and-warnings.rst new file mode 100644 index 0000000..871fe57 --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-command-options/options-to-request-or-suppress-errors-and-warnings.rst @@ -0,0 +1,411 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: options, warnings, options, errors, warnings, suppressing, messages, error, messages, warning, suppressing warnings + +.. _error-and-warning-options: + +Options to request or suppress errors and 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: + +.. index:: fmax-errors=n, errors, limiting + +.. option:: -fmax-errors={n} + + Limits the maximum number of error messages to :samp:`{n}`, at which point + GNU Fortran bails out rather than attempting to continue processing the + source code. If :samp:`{n}` is 0, there is no limit on the number of error + messages produced. + +.. index:: fsyntax-only, syntax checking + +.. option:: -fsyntax-only + + 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. + +.. index:: pedantic, Wpedantic + +.. option:: -Wpedantic, -pedantic + + 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 ``#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`. + +.. index:: pedantic-errors + +.. option:: -pedantic-errors + + Like :option:`-pedantic`, except that errors are produced rather than + warnings. + +.. index:: Wall, all warnings, warnings, all + +.. option:: -Wall + + 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`. + +.. index:: Waliasing, aliasing, warnings, aliasing + +.. option:: -Waliasing + + Warn about possible aliasing of dummy arguments. Specifically, it warns + if the same actual argument is associated with a dummy argument with + ``INTENT(IN)`` and a dummy argument with ``INTENT(OUT)`` in a call + with an explicit interface. + + The following example will trigger the warning. + + .. code-block:: fortran + + interface + subroutine bar(a,b) + integer, intent(in) :: a + integer, intent(out) :: b + end subroutine + end interface + integer :: a + + call bar(a,a) + +.. index:: Wampersand, warnings, ampersand, & + +.. option:: -Wampersand + + 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. + +.. index:: Warray-temporaries, warnings, array temporaries + +.. option:: -Warray-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. + +.. index:: Wc-binding-type, warning, C binding type + +.. option:: -Wc-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 ``ISO_C_Binding`` module. This option is implied by + :option:`-Wall`. + +.. index:: Wcharacter-truncation, warnings, character truncation + +.. option:: -Wcharacter-truncation + + Warn when a character assignment will truncate the assigned string. + +.. index:: Wline-truncation, warnings, line truncation + +.. option:: -Wline-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. + +.. index:: Wconversion, warnings, conversion, conversion + +.. option:: -Wconversion + + Warn about implicit conversions that are likely to change the value of + the expression after conversion. Implied by :option:`-Wall`. + +.. index:: Wconversion-extra, warnings, conversion, conversion + +.. option:: -Wconversion-extra + + Warn about implicit conversions between different types and kinds. This + option does *not* imply :option:`-Wconversion`. + +.. index:: Wextra, extra warnings, warnings, extra + +.. option:: -Wextra + + 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`. + +.. index:: Wfrontend-loop-interchange, warnings, loop interchange, loop interchange, warning + +.. option:: -Wfrontend-loop-interchange + + Warn when using :option:`-ffrontend-loop-interchange` for performing loop + interchanges. + +.. index:: Wimplicit-interface, warnings, implicit interface + +.. option:: -Wimplicit-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. + +.. index:: Wimplicit-procedure, warnings, implicit procedure + +.. option:: -Wimplicit-procedure + + Warn if a procedure is called that has neither an explicit interface + nor has been declared as ``EXTERNAL``. + +.. index:: Winteger-division, warnings, integer division, warnings, division of integers + +.. option:: -Winteger-division + + Warn if a constant integer division truncates its result. + As an example, 3/5 evaluates to 0. + +.. index:: Wintrinsics-std, warnings, non-standard intrinsics, warnings, intrinsics of other standards + +.. option:: -Wintrinsics-std + + 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 ``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. + +.. index:: Woverwrite-recursive, warnings, overwrite recursive + +.. option:: -Wno-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 + ``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`. + +.. index:: Wreal-q-constant, warnings, q exponent-letter + +.. option:: -Wreal-q-constant + + Produce a warning if a real-literal-constant contains a ``q`` + exponent-letter. + +.. index:: Wsurprising, warnings, suspicious code + +.. option:: -Wsurprising + + 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: + + * An INTEGER SELECT construct has a CASE that can never be matched as its + lower value is greater than its upper value. + + * A LOGICAL SELECT construct has three CASE statements. + + * A TRANSFER specifies a source that is shorter than the destination. + + * 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. + + * A ``CHARACTER`` variable is declared with negative length. + + * With :option:`-fopenmp`, for fixed-form source code, when an ``omx`` + vendor-extension sentinel is encountered. (The equivalent ``ompx``, + used in free-form source code, is diagnosed by default.) + +.. index:: Wtabs, warnings, tabs, tabulators + +.. option:: -Wtabs + + 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`. + +.. index:: Wundefined-do-loop, warnings, undefined do loop + +.. option:: -Wundefined-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`. + +.. index:: Wunderflow, warnings, underflow, underflow + +.. option:: -Wunderflow + + Produce a warning when numerical constant expressions are + encountered, which yield an UNDERFLOW during compilation. Enabled by default. + +.. index:: Wintrinsic-shadow, warnings, intrinsic, intrinsic + +.. option:: -Wintrinsic-shadow + + Warn if a user-defined procedure or module procedure has the same name as an + intrinsic; in this case, an explicit interface or ``EXTERNAL`` or + ``INTRINSIC`` declaration might be needed to get calls later resolved to + the desired intrinsic/procedure. This option is implied by :option:`-Wall`. + +.. index:: Wuse-without-only, warnings, use statements, intrinsic + +.. option:: -Wuse-without-only + + Warn if a ``USE`` statement has no ``ONLY`` qualifier and + thus implicitly imports all public entities of the used module. + +.. index:: Wunused-dummy-argument, warnings, unused dummy argument, unused dummy argument, dummy argument, unused + +.. option:: -Wunused-dummy-argument + + Warn about unused dummy arguments. This option is implied by :option:`-Wall`. + +.. index:: Wunused-parameter, warnings, unused parameter, unused parameter + +.. option:: -Wunused-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 ``PARAMETER`` values. :option:`-Wunused-parameter` + is implied by :option:`-Wextra` if also :option:`-Wunused` or + :option:`-Wall` is used. + +.. index:: Walign-commons, warnings, alignment of COMMON blocks, alignment of COMMON blocks + +.. option:: -Walign-commons + + By default, :command:`gfortran` warns about any occasion of variables being + padded for proper alignment inside a ``COMMON`` block. This warning can be turned + off via :option:`-Wno-align-commons`. See also :option:`-falign-commons`. + +.. index:: Wfunction-elimination, function elimination, warnings, function elimination + +.. option:: -Wfunction-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`. + +.. index:: Wrealloc-lhs, Reallocate the LHS in assignments, notification + +.. option:: -Wrealloc-lhs + + 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. ``(:,:,:)``) 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`. + +.. index:: Wrealloc-lhs-all + +.. option:: -Wrealloc-lhs-all + + Warn when the compiler inserts code to for allocation or reallocation of an + allocatable variable; this includes scalars and derived types. + +.. index:: Wcompare-reals + +.. option:: -Wcompare-reals + + Warn when comparing real or complex types for equality or inequality. + This option is implied by :option:`-Wextra`. + +.. index:: Wtargt-lifetime + +.. option:: -Wtarget-lifetime + + Warn if the pointer in a pointer assignment might be longer than the its + target. This option is implied by :option:`-Wall`. + +.. index:: Wzerotrip + +.. option:: -Wzerotrip + + Warn if a ``DO`` loop is known to execute zero times at compile + time. This option is implied by :option:`-Wall`. + +.. index:: Wdo-subscript + +.. option:: -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 + + .. code-block:: fortran + + real a(3) + do i=1,4 + if (condition(i)) then + a(i) = 1.2 + end if + end do + + This option is implied by :option:`-Wextra`. + +.. index:: Werror, warnings, to errors + +.. option:: -Werror + + Turns all warnings into errors. + +See :ref:`gcc:warning-options`, 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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-fortran-compiler-directives.rst b/gcc/fortran/doc/gfortran/gnu-fortran-compiler-directives.rst new file mode 100644 index 0000000..966be29 --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-fortran-compiler-directives.rst @@ -0,0 +1,174 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gnu-fortran-compiler-directives: + +GNU Fortran Compiler Directives +******************************* + +.. toctree:: + :maxdepth: 2 + + +.. _attributes-directive: + +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:`gcc:top` +for details. + +For procedures and procedure pointers, the following attributes can +be used to change the calling convention: + +* ``CDECL`` -- standard C calling convention + +* ``STDCALL`` -- convention where the called procedure pops the stack + +* ``FASTCALL`` -- part of the arguments are passed via registers + instead using the stack + +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 +``COMMON`` blocks) need special handling to be accessible when they +are in a shared library. The following attributes are available: + +* ``DLLEXPORT`` -- provide a global pointer to a pointer in the DLL + +* ``DLLIMPORT`` -- reference the function or variable using a + global pointer + +For dummy arguments, the ``NO_ARG_CHECK`` attribute can be used; in +other compilers, it is also known as ``IGNORE_TKR``. For dummy arguments +with this attribute actual arguments of any type and kind (similar to +``TYPE(*)``), scalars and arrays of any rank (no equivalent +in Fortran standard) are accepted. As with ``TYPE(*)``, the argument +is unlimited polymorphic and no type information is available. +Additionally, the argument may only be passed to dummy arguments +with the ``NO_ARG_CHECK`` attribute and as argument to the +``PRESENT`` intrinsic function and to ``C_LOC`` of the +``ISO_C_BINDING`` module. + +Variables with ``NO_ARG_CHECK`` attribute shall be of assumed-type +(``TYPE(*)`` ; recommended) or of type ``INTEGER``, ``LOGICAL``, +``REAL`` or ``COMPLEX``. They shall not have the ``ALLOCATE``, +``CODIMENSION``, ``INTENT(OUT)``, ``POINTER`` or ``VALUE`` +attribute; furthermore, they shall be either scalar or of assumed-size +(``dimension(*)``). As ``TYPE(*)``, the ``NO_ARG_CHECK`` attribute +requires an explicit interface. + +* ``NO_ARG_CHECK`` -- disable the type, kind and rank checking + +* ``DEPRECATED`` -- print a warning when using a such-tagged + deprecated procedure, variable or parameter; the warning can be suppressed + with :option:`-Wno-deprecated-declarations`. + +The attributes are specified using the syntax + +``!GCC$ ATTRIBUTES`` :samp:`{attribute-list}` ``::`` :samp:`{variable-list}` + +where in free-form source code only whitespace is allowed before ``!GCC$`` +and in fixed-form source code ``!GCC$``, ``cGCC$`` or ``*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. + +.. _unroll-directive: + +UNROLL directive +^^^^^^^^^^^^^^^^ + +The syntax of the directive is + +``!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 ``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. + +.. _builtin-directive: + +BUILTIN directive +^^^^^^^^^^^^^^^^^ + +The syntax of the directive is + +``!GCC$ BUILTIN (B) attributes simd FLAGS IF('target')`` + +You can use this directive to define which middle-end built-ins provide vector +implementations. ``B`` is name of the middle-end built-in. ``FLAGS`` +are optional and must be either "(inbranch)" or "(notinbranch)". +``IF`` statement is optional and is used to filter multilib ABIs +for the built-in that should be vectorized. Example usage: + +.. code-block:: fortran + + !GCC$ builtin (sinf) attributes simd (notinbranch) if('x86_64') + +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. + +.. _ivdep-directive: + +IVDEP directive +^^^^^^^^^^^^^^^ + +The syntax of the directive is + +``!GCC$ ivdep`` + +This directive tells the compiler to ignore vector dependencies in the +following loop. It must be placed immediately before a ``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. + +.. _vector-directive: + +VECTOR directive +^^^^^^^^^^^^^^^^ + +The syntax of the directive is + +``!GCC$ vector`` + +This directive tells the compiler to vectorize the following loop. It +must be placed immediately before a ``DO`` loop and applies only to +the loop that follows. + +.. _novector-directive: + +NOVECTOR directive +^^^^^^^^^^^^^^^^^^ + +The syntax of the directive is + +``!GCC$ novector`` + +This directive tells the compiler to not vectorize the following loop. +It must be placed immediately before a ``DO`` loop and applies only +to the loop that follows.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/gnu-free-documentation-license.rst b/gcc/fortran/doc/gfortran/gnu-free-documentation-license.rst new file mode 100644 index 0000000..9a3dac6 --- /dev/null +++ b/gcc/fortran/doc/gfortran/gnu-free-documentation-license.rst @@ -0,0 +1,6 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. include:: ../../../../doc/gnu_free_documentation_license.rst
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/index.rst b/gcc/fortran/doc/gfortran/index.rst new file mode 100644 index 0000000..312da78 --- /dev/null +++ b/gcc/fortran/doc/gfortran/index.rst @@ -0,0 +1,56 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +The GNU Fortran Compiler +======================== + +.. index:: 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. + +.. only:: development + + .. 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. + +.. toctree:: + :maxdepth: 3 + + copyright + introduction + +Part I: Invoking GNU Fortran +---------------------------- + +.. toctree:: + :maxdepth: 3 + + gnu-fortran-command-options + runtime + +Part II: Language Reference +--------------------------- + +.. toctree:: + :maxdepth: 3 + + compiler-characteristics + extensions + mixed-language-programming + coarray-programming + intrinsic-procedures + intrinsic-modules + + contributing + general-public-license-3 + gnu-free-documentation-license + funding + + indices-and-tables
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/indices-and-tables.rst b/gcc/fortran/doc/gfortran/indices-and-tables.rst new file mode 100644 index 0000000..50865c6 --- /dev/null +++ b/gcc/fortran/doc/gfortran/indices-and-tables.rst @@ -0,0 +1 @@ +.. include:: ../../../../doc/indices-and-tables.rst
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/interoperability-with-c.rst b/gcc/fortran/doc/gfortran/interoperability-with-c.rst new file mode 100644 index 0000000..52364ad --- /dev/null +++ b/gcc/fortran/doc/gfortran/interoperability-with-c.rst @@ -0,0 +1,413 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: interoperability with C, C interoperability + +.. _interoperability-with-c: + +Interoperability with C +*********************** + +.. toctree:: + :maxdepth: 2 + +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 ``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 ``A(n,m)`` in Fortran matches +``A[m][n]`` in C and accessing the element ``A(i,j)`` matches +``A[j-1][i-1]``. The element following ``A(i,j)`` (C: ``A[j-1][i-1]`` ; +assuming i < n) in memory is ``A(i+1,j)`` (C: ``A[j-1][i]``). + +.. index:: C intrinsic type interoperability, intrinsic type interoperability with C, interoperability, intrinsic type + +.. _intrinsic-types: + +Intrinsic Types +^^^^^^^^^^^^^^^ + +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 ``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 ``_Bool`` and Fortran's ``C_Bool`` -kind +logicals and C99 defines that ``true`` has the value 1 and ``false`` +the value 0. Using any other integer value with GNU Fortran's ``LOGICAL`` +(with any kind parameter) gives an undefined result. (Passing other integer +values than 0 and 1 to GCC's ``_Bool`` is also undefined, unless the +integer is explicitly or implicitly casted to ``_Bool``.) + +.. index:: C derived type and struct interoperability, derived type interoperability with C, interoperability, derived type and struct + +.. _derived-types-and-struct: + +Derived Types and struct +^^^^^^^^^^^^^^^^^^^^^^^^ + +For compatibility of derived types with ``struct``, use +the ``BIND(C)`` attribute in the type declaration. For instance, the +following type declaration + +.. code-block:: fortran + + 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 + +matches the following ``struct`` declaration in C + +.. code-block:: c + + struct { + int i1, i2; + /* Note: "char" might be signed or unsigned. */ + signed char i3; + double d1; + float _Complex c1; + char str[5]; + } myType; + +Derived types with the C binding attribute shall not have the ``sequence`` +attribute, type parameters, the ``extends`` attribute, nor type-bound +procedures. Every component must be of interoperable type and kind and may not +have the ``pointer`` or ``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. + +.. index:: C variable interoperability, variable interoperability with C, interoperability, variable + +.. _interoperable-global-variables: + +Interoperable Global Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 ``MODULE``, +be of interoperable type, and have neither the ``pointer`` nor +the ``allocatable`` attribute. + +.. code-block:: fortran + + 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 + +Here, ``_MyProject_flags`` is the case-sensitive name of the variable +as seen from C programs while ``global_flag`` is the case-insensitive +name as seen from Fortran. If no binding name is specified, as for +:samp:`{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 :samp:`{errno}` of the C library as the C standard allows it to be +a macro. Use the ``IERRNO`` intrinsic (GNU extension) instead. + +.. index:: C procedure interoperability, procedure interoperability with C, function interoperability with C, subroutine interoperability with C, interoperability, subroutine and function + +.. _interoperable-subroutines-and-functions: + +Interoperable Subroutines and Functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Subroutines and functions have to have the ``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 ``VALUE`` attribute. +Thus, the following C prototype + +.. code-block:: fortran + + int func(int i, int *j) + +matches the Fortran declaration + +.. code-block:: fortran + + integer(c_int) function func(i,j) + use iso_c_binding, only: c_int + integer(c_int), VALUE :: i + integer(c_int) :: j + +Note that pointer arguments also frequently need the ``VALUE`` attribute, +see :ref:`working-with-c-pointers`. + +Strings are handled quite differently in C and Fortran. In C a string +is a ``NUL`` -terminated array of characters while in Fortran each string +has a length associated with it and is thus not terminated (by e.g. +``NUL``). For example, if you want to use the following C function, + +.. code-block:: c + + #include <stdio.h> + void print_C(char *string) /* equivalent: char string[] */ + { + printf("%s\n", string); + } + +to print 'Hello World' from Fortran, you can call it using + +.. code-block:: fortran + + 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) + +As the example shows, you need to ensure that the +string is ``NUL`` terminated. Additionally, the dummy argument +:samp:`{string}` of ``print_C`` is a length-one assumed-size +array; using ``character(len=*)`` is not allowed. The example +above uses ``c_char_"Hello World"`` to ensure the string +literal has the right type; typically the default character +kind and ``c_char`` are the same and thus ``"Hello World"`` +is equivalent. However, the standard does not guarantee this. + +The use of strings is now further illustrated using the C library +function ``strncpy``, whose prototype is + +.. code-block:: c + + char *strncpy(char *restrict s1, const char *restrict s2, size_t n); + +The function ``strncpy`` copies at most :samp:`{n}` characters from +string :samp:`{s2}` to :samp:`{s1}` and returns :samp:`{s1}`. In the following +example, we ignore the return value: + +.. code-block:: fortran + + 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 + +The intrinsic procedures are described in :ref:`intrinsic-procedures`. + +.. index:: C pointers, pointers, C + +.. _working-with-c-pointers: + +Working with C Pointers +^^^^^^^^^^^^^^^^^^^^^^^ + +C pointers are represented in Fortran via the special opaque derived +type ``type(c_ptr)`` (with private components). C pointers are distinct +from Fortran objects with the ``POINTER`` attribute. Thus one needs to +use intrinsic conversion procedures to convert from or to C pointers. +For some applications, using an assumed type (``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: + +.. code-block:: fortran + + 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]) + +When converting C to Fortran arrays, the one-dimensional ``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 ``VALUE`` attribute. ``void*`` +matches ``TYPE(C_PTR), VALUE``, while ``TYPE(C_PTR)`` alone +matches ``void**``. + +Procedure pointers are handled analogously to pointers; the C type is +``TYPE(C_FUNPTR)`` and the intrinsic conversion procedures are +``C_F_PROCPOINTER`` and ``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: + +.. code-block:: c + + /* 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); + } + +A matching implementation for ``get_values`` in Fortran, that correctly +receives the procedure pointer from C and is able to call it, is given +in the following ``MODULE`` : + +.. code-block:: fortran + + 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 + +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: + +.. code-block:: c + + int + call_it (int (*func)(int), int arg) + { + return func (arg); + } + +It can be used as in the following Fortran code: + +.. code-block:: fortran + + 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 + +.. index:: Further Interoperability of Fortran with C, TS 29113, array descriptor, dope vector, assumed-type, assumed-rank + +.. _further-interoperability-of-fortran-with-c: + +Further Interoperability of Fortran with C +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 (``TYPE(*)``) and assumed-rank +(``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 +``BIND(C)`` functions as descriptors with a standard interface, +declared in the header file ``<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 +``BIND(C)`` attribute. Arguments to functions marked ``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, http://chasm-interop.sourceforge.net/.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-modules.rst b/gcc/fortran/doc/gfortran/intrinsic-modules.rst new file mode 100644 index 0000000..3768d4f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-modules.rst @@ -0,0 +1,20 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: intrinsic Modules + +.. _intrinsic-modules: + +Intrinsic Modules +----------------- + +.. toctree:: + :maxdepth: 2 + + intrinsic-modules/openacc-module-openacc + intrinsic-modules/isofortranenv + intrinsic-modules/isocbinding + intrinsic-modules/ieee-modules-ieeeexceptions-ieeearithmetic-and-ieeefeatures + intrinsic-modules/openmp-modules-omplib-and-omplibkinds
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-modules/ieee-modules-ieeeexceptions-ieeearithmetic-and-ieeefeatures.rst b/gcc/fortran/doc/gfortran/intrinsic-modules/ieee-modules-ieeeexceptions-ieeearithmetic-and-ieeefeatures.rst new file mode 100644 index 0000000..4bdf249 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-modules/ieee-modules-ieeeexceptions-ieeearithmetic-and-ieeefeatures.rst @@ -0,0 +1,29 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ieee-modules: + +IEEE modules: IEEE_EXCEPTIONS, IEEE_ARITHMETIC, and IEEE_FEATURES +***************************************************************** + +:samp:`{Standard}:` + Fortran 2003 and later + + The ``IEEE_EXCEPTIONS``, ``IEEE_ARITHMETIC``, and ``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 + (*Binary floating-point arithmetic for microprocessor systems*). These + modules are only provided on the following supported platforms: + + * i386 and x86_64 processors + * platforms which use the GNU C Library (glibc) + * platforms with support for SysV/386 routines for floating point + interface (including Solaris and BSDs) + * platforms with the AIX OS + +For full compliance with the Fortran standards, code using the +``IEEE_EXCEPTIONS`` or ``IEEE_ARITHMETIC`` modules should be compiled +with the following options: ``-fno-unsafe-math-optimizations +-frounding-math -fsignaling-nans``.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-modules/isocbinding.rst b/gcc/fortran/doc/gfortran/intrinsic-modules/isocbinding.rst new file mode 100644 index 0000000..3750eda --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-modules/isocbinding.rst @@ -0,0 +1,227 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _iso_c_binding: + +ISO_C_BINDING +************* + +:samp:`{Standard}:` + Fortran 2003 and later, GNU extensions + + The following intrinsic procedures are provided by the module; their + definition can be found in the section Intrinsic Procedures of this + manual. + +* C_ASSOCIATED +* C_F_POINTER +* C_F_PROCPOINTER +* C_FUNLOCC_LOC +* C_SIZEOF + +The ``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 ``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: ``C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T``. +Furthermore, if ``_Float128`` is supported in C, the named constants +``C_FLOAT128`` and ``C_FLOAT128_COMPLEX`` are defined. + +.. list-table:: + :header-rows: 1 + + * - Fortran Type + - Named constant + - C type + - Extension + + * - ``INTEGER`` + - ``C_INT`` + - ``int`` + - + * - ``INTEGER`` + - ``C_SHORT`` + - ``short int`` + - + * - ``INTEGER`` + - ``C_LONG`` + - ``long int`` + - + * - ``INTEGER`` + - ``C_LONG_LONG`` + - ``long long int`` + - + * - ``INTEGER`` + - ``C_SIGNED_CHAR`` + - ``signed char`` / ``unsigned char`` + - + * - ``INTEGER`` + - ``C_SIZE_T`` + - ``size_t`` + - + * - ``INTEGER`` + - ``C_INT8_T`` + - ``int8_t`` + - + * - ``INTEGER`` + - ``C_INT16_T`` + - ``int16_t`` + - + * - ``INTEGER`` + - ``C_INT32_T`` + - ``int32_t`` + - + * - ``INTEGER`` + - ``C_INT64_T`` + - ``int64_t`` + - + * - ``INTEGER`` + - ``C_INT128_T`` + - ``int128_t`` + - Ext. + * - ``INTEGER`` + - ``C_INT_LEAST8_T`` + - ``int_least8_t`` + - + * - ``INTEGER`` + - ``C_INT_LEAST16_T`` + - ``int_least16_t`` + - + * - ``INTEGER`` + - ``C_INT_LEAST32_T`` + - ``int_least32_t`` + - + * - ``INTEGER`` + - ``C_INT_LEAST64_T`` + - ``int_least64_t`` + - + * - ``INTEGER`` + - ``C_INT_LEAST128_T`` + - ``int_least128_t`` + - Ext. + * - ``INTEGER`` + - ``C_INT_FAST8_T`` + - ``int_fast8_t`` + - + * - ``INTEGER`` + - ``C_INT_FAST16_T`` + - ``int_fast16_t`` + - + * - ``INTEGER`` + - ``C_INT_FAST32_T`` + - ``int_fast32_t`` + - + * - ``INTEGER`` + - ``C_INT_FAST64_T`` + - ``int_fast64_t`` + - + * - ``INTEGER`` + - ``C_INT_FAST128_T`` + - ``int_fast128_t`` + - Ext. + * - ``INTEGER`` + - ``C_INTMAX_T`` + - ``intmax_t`` + - + * - ``INTEGER`` + - ``C_INTPTR_T`` + - ``intptr_t`` + - + * - ``INTEGER`` + - ``C_PTRDIFF_T`` + - ``ptrdiff_t`` + - TS 29113 + * - ``REAL`` + - ``C_FLOAT`` + - ``float`` + - + * - ``REAL`` + - ``C_DOUBLE`` + - ``double`` + - + * - ``REAL`` + - ``C_LONG_DOUBLE`` + - ``long double`` + - + * - ``REAL`` + - ``C_FLOAT128`` + - ``_Float128`` + - Ext. + * - ``COMPLEX`` + - ``C_FLOAT_COMPLEX`` + - ``float _Complex`` + - + * - ``COMPLEX`` + - ``C_DOUBLE_COMPLEX`` + - ``double _Complex`` + - + * - ``COMPLEX`` + - ``C_LONG_DOUBLE_COMPLEX`` + - ``long double _Complex`` + - + * - ``COMPLEX`` + - ``C_FLOAT128_COMPLEX`` + - ``_Float128 _Complex`` + - Ext. + * - ``LOGICAL`` + - ``C_BOOL`` + - ``_Bool`` + - + * - ``CHARACTER`` + - ``C_CHAR`` + - ``char`` + - + +Additionally, the following parameters of type ``CHARACTER(KIND=C_CHAR)`` +are defined. + +.. list-table:: + :header-rows: 1 + + * - Name + - C definition + - Value + + * - ``C_NULL_CHAR`` + - null character + - ``'\0'`` + * - ``C_ALERT`` + - alert + - ``'\a'`` + * - ``C_BACKSPACE`` + - backspace + - ``'\b'`` + * - ``C_FORM_FEED`` + - form feed + - ``'\f'`` + * - ``C_NEW_LINE`` + - new line + - ``'\n'`` + * - ``C_CARRIAGE_RETURN`` + - carriage return + - ``'\r'`` + * - ``C_HORIZONTAL_TAB`` + - horizontal tab + - ``'\t'`` + * - ``C_VERTICAL_TAB`` + - vertical tab + - ``'\v'`` + +Moreover, the following two named constants are defined: + +.. list-table:: + :header-rows: 1 + + * - Name + - Type + + * - ``C_NULL_PTR`` + - ``C_PTR`` + * - ``C_NULL_FUNPTR`` + - ``C_FUNPTR`` + +Both are equivalent to the value ``NULL`` in C.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-modules/isofortranenv.rst b/gcc/fortran/doc/gfortran/intrinsic-modules/isofortranenv.rst new file mode 100644 index 0000000..a03e1eb --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-modules/isofortranenv.rst @@ -0,0 +1,116 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _iso_fortran_env: + +ISO_FORTRAN_ENV +*************** + +:samp:`{Standard}:` + Fortran 2003 and later, except when otherwise noted + + The ``ISO_FORTRAN_ENV`` module provides the following scalar default-integer named constants: + +:samp:`{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.) + +:samp:`{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.) + +:samp:`{CHARACTER_KINDS}:` + Default-kind integer constant array of rank one containing the supported kind + parameters of the ``CHARACTER`` type. (Fortran 2008 or later.) + +:samp:`{CHARACTER_STORAGE_SIZE}:` + Size in bits of the character storage unit. + +:samp:`{ERROR_UNIT}:` + Identifies the preconnected unit used for error reporting. + +:samp:`{FILE_STORAGE_SIZE}:` + Size in bits of the file-storage unit. + +:samp:`{INPUT_UNIT}:` + Identifies the preconnected unit identified by the asterisk + (``*``) in ``READ`` statement. + +:samp:`{INT8}, {INT16}, {INT32}, {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.) + +:samp:`{INTEGER_KINDS}:` + Default-kind integer constant array of rank one containing the supported kind + parameters of the ``INTEGER`` type. (Fortran 2008 or later.) + +:samp:`{IOSTAT_END}:` + The value assigned to the variable passed to the ``IOSTAT=`` specifier of + an input/output statement if an end-of-file condition occurred. + +:samp:`{IOSTAT_EOR}:` + The value assigned to the variable passed to the ``IOSTAT=`` specifier of + an input/output statement if an end-of-record condition occurred. + +:samp:`{IOSTAT_INQUIRE_INTERNAL_UNIT}:` + Scalar default-integer constant, used by ``INQUIRE`` for the + ``IOSTAT=`` specifier to denote an that a unit number identifies an + internal unit. (Fortran 2008 or later.) + +:samp:`{NUMERIC_STORAGE_SIZE}:` + The size in bits of the numeric storage unit. + +:samp:`{LOGICAL_KINDS}:` + Default-kind integer constant array of rank one containing the supported kind + parameters of the ``LOGICAL`` type. (Fortran 2008 or later.) + +:samp:`{OUTPUT_UNIT}:` + Identifies the preconnected unit identified by the asterisk + (``*``) in ``WRITE`` statement. + +:samp:`{REAL32}, {REAL64}, {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.) + +:samp:`{REAL_KINDS}:` + Default-kind integer constant array of rank one containing the supported kind + parameters of the ``REAL`` type. (Fortran 2008 or later.) + +:samp:`{STAT_LOCKED}:` + Scalar default-integer constant used as STAT= return value by ``LOCK`` to + denote that the lock variable is locked by the executing image. (Fortran 2008 + or later.) + +:samp:`{STAT_LOCKED_OTHER_IMAGE}:` + Scalar default-integer constant used as STAT= return value by ``UNLOCK`` to + denote that the lock variable is locked by another image. (Fortran 2008 or + later.) + +:samp:`{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.) + +:samp:`{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.) + +:samp:`{STAT_UNLOCKED}:` + Scalar default-integer constant used as STAT= return value by ``UNLOCK`` to + denote that the lock variable is unlocked. (Fortran 2008 or later.) + + The module provides the following derived type: + +:samp:`{LOCK_TYPE}:` + Derived type with private components to be use with the ``LOCK`` and + ``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.) + + The module also provides the following intrinsic procedures: + :ref:`COMPILER_OPTIONS` and :ref:`COMPILER_VERSION`.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-modules/openacc-module-openacc.rst b/gcc/fortran/doc/gfortran/intrinsic-modules/openacc-module-openacc.rst new file mode 100644 index 0000000..56a5d37 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-modules/openacc-module-openacc.rst @@ -0,0 +1,27 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _openacc-module-openacc: + +OpenACC Module OPENACC +********************** + +:samp:`{Standard}:` + OpenACC Application Programming Interface v2.6 + + The OpenACC Fortran runtime library routines are provided both in a + form of a Fortran 90 module, named ``OPENACC``, and in form of a + Fortran ``include`` file named :samp:`openacc_lib.h`. The + procedures provided by ``OPENACC`` can be found in the + :ref:`libgomp:top` manual, the named constants defined in the modules + are listed below. + +For details refer to the actual +`OpenACC Application Programming Interface v2.6 <https://www.openacc.org/>`_. + +``OPENACC`` provides the scalar default-integer +named constant ``openacc_version`` with a value of the form +:samp:`{yyyymm}`, where ``yyyy`` is the year and :samp:`{mm}` the month +of the OpenACC version; for OpenACC v2.6 the value is ``201711``.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-modules/openmp-modules-omplib-and-omplibkinds.rst b/gcc/fortran/doc/gfortran/intrinsic-modules/openmp-modules-omplib-and-omplibkinds.rst new file mode 100644 index 0000000..56951f3 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-modules/openmp-modules-omplib-and-omplibkinds.rst @@ -0,0 +1,161 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _openmp-modules-omp_lib-and-omp_lib_kinds: + +OpenMP Modules OMP_LIB and OMP_LIB_KINDS +**************************************** + +The OpenMP Fortran runtime library routines are provided both in +a form of two Fortran modules, named ``OMP_LIB`` and +``OMP_LIB_KINDS``, and in a form of a Fortran ``include`` file named +:samp:`omp_lib.h`. The procedures provided by ``OMP_LIB`` can be found +in the :ref:`libgomp:top` manual, +the named constants defined in the modules are listed +below. + +For details refer to the actual +`OpenMP Application Program Interface v4.5 <https://www.openmp.org/wp-content/uploads/openmp-4.5.pdf>`_ and +`OpenMP Application Program Interface v5.0 <https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5.0.pdf>`_. + +``OMP_LIB_KINDS`` provides the following scalar default-integer +named constants: + +.. code-block:: + + omp_allocator_handle_kind + omp_alloctrait_key_kind + omp_alloctrait_val_kind + omp_depend_kind + omp_lock_kind + omp_lock_hint_kind + omp_nest_lock_kind + omp_pause_resource_kind + omp_memspace_handle_kind + omp_proc_bind_kind + omp_sched_kind + omp_sync_hint_kind + +``OMP_LIB`` provides the scalar default-integer +named constant ``openmp_version`` with a value of the form +:samp:`{yyyymm}`, where ``yyyy`` is the year and :samp:`{mm}` the month +of the OpenMP version; for OpenMP v4.5 the value is ``201511``. + +The following derived type: + +.. code-block:: + + omp_alloctrait + +The following scalar integer named constants of the +kind ``omp_sched_kind`` : + +.. code-block:: + + omp_sched_static + omp_sched_dynamic + omp_sched_guided + omp_sched_auto + +And the following scalar integer named constants of the +kind ``omp_proc_bind_kind`` : + +.. code-block:: + + omp_proc_bind_false + omp_proc_bind_true + omp_proc_bind_primary + omp_proc_bind_master + omp_proc_bind_close + omp_proc_bind_spread + +The following scalar integer named constants are of the +kind ``omp_lock_hint_kind`` : + +.. code-block:: + + omp_lock_hint_none + omp_lock_hint_uncontended + omp_lock_hint_contended + omp_lock_hint_nonspeculative + omp_lock_hint_speculative + omp_sync_hint_none + omp_sync_hint_uncontended + omp_sync_hint_contended + omp_sync_hint_nonspeculative + omp_sync_hint_speculative + +And the following two scalar integer named constants are of the +kind ``omp_pause_resource_kind`` : + +.. code-block:: + + omp_pause_soft + omp_pause_hard + +The following scalar integer named constants are of the kind +``omp_alloctrait_key_kind`` : + +.. code-block:: + + omp_atk_sync_hint + omp_atk_alignment + omp_atk_access + omp_atk_pool_size + omp_atk_fallback + omp_atk_fb_data + omp_atk_pinned + omp_atk_partition + +The following scalar integer named constants are of the kind +``omp_alloctrait_val_kind`` : + +.. code-block:: + + omp_atv_default + omp_atv_false + omp_atv_true + omp_atv_contended + omp_atv_uncontended + omp_atv_serialized + omp_atv_sequential + omp_atv_private + omp_atv_all + omp_atv_thread + omp_atv_pteam + omp_atv_cgroup + omp_atv_default_mem_fb + omp_atv_null_fb + omp_atv_abort_fb + omp_atv_allocator_fb + omp_atv_environment + omp_atv_nearest + omp_atv_blocked + +The following scalar integer named constants are of the kind +``omp_allocator_handle_kind`` : + +.. code-block:: + + omp_null_allocator + omp_default_mem_alloc + omp_large_cap_mem_alloc + omp_const_mem_alloc + omp_high_bw_mem_alloc + omp_low_lat_mem_alloc + omp_cgroup_mem_alloc + omp_pteam_mem_alloc + omp_thread_mem_alloc + +The following scalar integer named constants are of the kind +``omp_memspace_handle_kind`` : + +.. code-block:: + + omp_default_mem_space + omp_large_cap_mem_space + omp_const_mem_space + omp_high_bw_mem_space + omp_low_lat_mem_space
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures.rst new file mode 100644 index 0000000..cf1b0c9 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures.rst @@ -0,0 +1,299 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: intrinsic procedures + +.. _intrinsic-procedures: + +Intrinsic Procedures +-------------------- + +.. toctree:: + :maxdepth: 2 + + + intrinsic-procedures/introduction-to-intrinsic-procedures + intrinsic-procedures/abort + intrinsic-procedures/abs + intrinsic-procedures/access + intrinsic-procedures/achar + intrinsic-procedures/acos + intrinsic-procedures/acosd + intrinsic-procedures/acosh + intrinsic-procedures/adjustl + intrinsic-procedures/adjustr + intrinsic-procedures/aimag + intrinsic-procedures/aint + intrinsic-procedures/alarm + intrinsic-procedures/all + intrinsic-procedures/allocated + intrinsic-procedures/and + intrinsic-procedures/anint + intrinsic-procedures/any + intrinsic-procedures/asin + intrinsic-procedures/asind + intrinsic-procedures/asinh + intrinsic-procedures/associated + intrinsic-procedures/atan + intrinsic-procedures/atand + intrinsic-procedures/atan2 + intrinsic-procedures/atan2d + intrinsic-procedures/atanh + intrinsic-procedures/atomicadd + intrinsic-procedures/atomicand + intrinsic-procedures/atomiccas + intrinsic-procedures/atomicdefine + intrinsic-procedures/atomicfetchadd + intrinsic-procedures/atomicfetchand + intrinsic-procedures/atomicfetchor + intrinsic-procedures/atomicfetchxor + intrinsic-procedures/atomicor + intrinsic-procedures/atomicref + intrinsic-procedures/atomicxor + intrinsic-procedures/backtrace + intrinsic-procedures/besselj0 + intrinsic-procedures/besselj1 + intrinsic-procedures/besseljn + intrinsic-procedures/bessely0 + intrinsic-procedures/bessely1 + intrinsic-procedures/besselyn + intrinsic-procedures/bge + intrinsic-procedures/bgt + intrinsic-procedures/bitsize + intrinsic-procedures/ble + intrinsic-procedures/blt + intrinsic-procedures/btest + intrinsic-procedures/cassociated + intrinsic-procedures/cfpointer + intrinsic-procedures/cfprocpointer + intrinsic-procedures/cfunloc + intrinsic-procedures/cloc + intrinsic-procedures/csizeof + intrinsic-procedures/ceiling + intrinsic-procedures/char + intrinsic-procedures/chdir + intrinsic-procedures/chmod + intrinsic-procedures/cmplx + intrinsic-procedures/cobroadcast + intrinsic-procedures/comax + intrinsic-procedures/comin + intrinsic-procedures/coreduce + intrinsic-procedures/cosum + intrinsic-procedures/commandargumentcount + intrinsic-procedures/compileroptions + intrinsic-procedures/compilerversion + intrinsic-procedures/complex + intrinsic-procedures/conjg + intrinsic-procedures/cos + intrinsic-procedures/cosd + intrinsic-procedures/cosh + intrinsic-procedures/cotan + intrinsic-procedures/cotand + intrinsic-procedures/count + intrinsic-procedures/cputime + intrinsic-procedures/cshift + intrinsic-procedures/ctime + intrinsic-procedures/dateandtime + intrinsic-procedures/dble + intrinsic-procedures/dcmplx + intrinsic-procedures/digits + intrinsic-procedures/dim + intrinsic-procedures/dotproduct + intrinsic-procedures/dprod + intrinsic-procedures/dreal + intrinsic-procedures/dshiftl + intrinsic-procedures/dshiftr + intrinsic-procedures/dtime + intrinsic-procedures/eoshift + intrinsic-procedures/epsilon + intrinsic-procedures/erf + intrinsic-procedures/erfc + intrinsic-procedures/erfcscaled + intrinsic-procedures/etime + intrinsic-procedures/eventquery + intrinsic-procedures/executecommandline + intrinsic-procedures/exit + intrinsic-procedures/exp + intrinsic-procedures/exponent + intrinsic-procedures/extendstypeof + intrinsic-procedures/fdate + intrinsic-procedures/fget + intrinsic-procedures/fgetc + intrinsic-procedures/findloc + intrinsic-procedures/floor + intrinsic-procedures/flush + intrinsic-procedures/fnum + intrinsic-procedures/fput + intrinsic-procedures/fputc + intrinsic-procedures/fraction + intrinsic-procedures/free + intrinsic-procedures/fseek + intrinsic-procedures/fstat + intrinsic-procedures/ftell + intrinsic-procedures/gamma + intrinsic-procedures/gerror + intrinsic-procedures/getarg + intrinsic-procedures/getcommand + intrinsic-procedures/getcommandargument + intrinsic-procedures/getcwd + intrinsic-procedures/getenv + intrinsic-procedures/getenvironmentvariable + intrinsic-procedures/getgid + intrinsic-procedures/getlog + intrinsic-procedures/getpid + intrinsic-procedures/getuid + intrinsic-procedures/gmtime + intrinsic-procedures/hostnm + intrinsic-procedures/huge + intrinsic-procedures/hypot + intrinsic-procedures/iachar + intrinsic-procedures/iall + intrinsic-procedures/iand + intrinsic-procedures/iany + intrinsic-procedures/iargc + intrinsic-procedures/ibclr + intrinsic-procedures/ibits + intrinsic-procedures/ibset + intrinsic-procedures/ichar + intrinsic-procedures/idate + intrinsic-procedures/ieor + intrinsic-procedures/ierrno + intrinsic-procedures/imageindex + intrinsic-procedures/index + intrinsic-procedures/int + intrinsic-procedures/int2 + intrinsic-procedures/int8 + intrinsic-procedures/ior + intrinsic-procedures/iparity + intrinsic-procedures/irand + intrinsic-procedures/iscontiguous + intrinsic-procedures/isiostatend + intrinsic-procedures/isiostateor + intrinsic-procedures/isatty + intrinsic-procedures/ishft + intrinsic-procedures/ishftc + intrinsic-procedures/isnan + intrinsic-procedures/itime + intrinsic-procedures/kill + intrinsic-procedures/kind + intrinsic-procedures/lbound + intrinsic-procedures/lcobound + intrinsic-procedures/leadz + intrinsic-procedures/len + intrinsic-procedures/lentrim + intrinsic-procedures/lge + intrinsic-procedures/lgt + intrinsic-procedures/link + intrinsic-procedures/lle + intrinsic-procedures/llt + intrinsic-procedures/lnblnk + intrinsic-procedures/loc + intrinsic-procedures/log + intrinsic-procedures/log10 + intrinsic-procedures/loggamma + intrinsic-procedures/logical + intrinsic-procedures/lshift + intrinsic-procedures/lstat + intrinsic-procedures/ltime + intrinsic-procedures/malloc + intrinsic-procedures/maskl + intrinsic-procedures/maskr + intrinsic-procedures/matmul + intrinsic-procedures/max + intrinsic-procedures/maxexponent + intrinsic-procedures/maxloc + intrinsic-procedures/maxval + intrinsic-procedures/mclock + intrinsic-procedures/mclock8 + intrinsic-procedures/merge + intrinsic-procedures/mergebits + intrinsic-procedures/min + intrinsic-procedures/minexponent + intrinsic-procedures/minloc + intrinsic-procedures/minval + intrinsic-procedures/mod + intrinsic-procedures/modulo + intrinsic-procedures/movealloc + intrinsic-procedures/mvbits + intrinsic-procedures/nearest + intrinsic-procedures/newline + intrinsic-procedures/nint + intrinsic-procedures/norm2 + intrinsic-procedures/not + intrinsic-procedures/null + intrinsic-procedures/numimages + intrinsic-procedures/or + intrinsic-procedures/pack + intrinsic-procedures/parity + intrinsic-procedures/perror + intrinsic-procedures/popcnt + intrinsic-procedures/poppar + intrinsic-procedures/precision + intrinsic-procedures/present + intrinsic-procedures/product + intrinsic-procedures/radix + intrinsic-procedures/ran + intrinsic-procedures/rand + intrinsic-procedures/randominit + intrinsic-procedures/randomnumber + intrinsic-procedures/randomseed + intrinsic-procedures/range + intrinsic-procedures/rank + intrinsic-procedures/real + intrinsic-procedures/rename + intrinsic-procedures/repeat + intrinsic-procedures/reshape + intrinsic-procedures/rrspacing + intrinsic-procedures/rshift + intrinsic-procedures/sametypeas + intrinsic-procedures/scale + intrinsic-procedures/scan + intrinsic-procedures/secnds + intrinsic-procedures/second + intrinsic-procedures/selectedcharkind + intrinsic-procedures/selectedintkind + intrinsic-procedures/selectedrealkind + intrinsic-procedures/setexponent + intrinsic-procedures/shape + intrinsic-procedures/shifta + intrinsic-procedures/shiftl + intrinsic-procedures/shiftr + intrinsic-procedures/sign + intrinsic-procedures/signal + intrinsic-procedures/sin + intrinsic-procedures/sind + intrinsic-procedures/sinh + intrinsic-procedures/size + intrinsic-procedures/sizeof + intrinsic-procedures/sleep + intrinsic-procedures/spacing + intrinsic-procedures/spread + intrinsic-procedures/sqrt + intrinsic-procedures/srand + intrinsic-procedures/stat + intrinsic-procedures/storagesize + intrinsic-procedures/sum + intrinsic-procedures/symlnk + intrinsic-procedures/system + intrinsic-procedures/systemclock + intrinsic-procedures/tan + intrinsic-procedures/tand + intrinsic-procedures/tanh + intrinsic-procedures/thisimage + intrinsic-procedures/time + intrinsic-procedures/time8 + intrinsic-procedures/tiny + intrinsic-procedures/trailz + intrinsic-procedures/transfer + intrinsic-procedures/transpose + intrinsic-procedures/trim + intrinsic-procedures/ttynam + intrinsic-procedures/ubound + intrinsic-procedures/ucobound + intrinsic-procedures/umask + intrinsic-procedures/unlink + intrinsic-procedures/unpack + intrinsic-procedures/verify + intrinsic-procedures/xor
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/abort.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/abort.rst new file mode 100644 index 0000000..9ac38fa --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/abort.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _abort: + +ABORT --- Abort the program +*************************** + +.. index:: ABORT, program termination, with core dump, terminate program, with core dump, core, dump + +.. function:: ABORT() + + ``ABORT`` causes immediate termination of the program. On operating + systems that support a core dump, ``ABORT`` will produce a core dump. + It will also print a backtrace, unless ``-fno-backtrace`` is given. + + :return: + Does not return. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL ABORT + + Example: + .. code-block:: fortran + + program test_abort + integer :: i = 1, j = 2 + if (i /= j) call abort + end program test_abort + + See also: + :ref:`EXIT`, + :ref:`KILL`, + :ref:`BACKTRACE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/abs.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/abs.rst new file mode 100644 index 0000000..ecc7495 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/abs.rst @@ -0,0 +1,117 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _abs: + +.. index:: ABS + +.. index:: CABS + +.. index:: DABS + +.. index:: IABS + +.. index:: ZABS + +.. index:: CDABS + +.. index:: BABS + +.. index:: IIABS + +.. index:: JIABS + +.. index:: KIABS + +.. index:: absolute value + +ABS --- Absolute value +********************** + +.. function:: ABS(A) + + ``ABS(A)`` computes the absolute value of ``A``. + + :param A: + The type of the argument shall be an ``INTEGER``, + ``REAL``, or ``COMPLEX``. + + :return: + The return value is of the same type and + kind as the argument except the return value is ``REAL`` for a + ``COMPLEX`` argument. + + Standard: + Fortran 77 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ABS(A) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ABS(A)`` + - ``REAL(4) A`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``CABS(A)`` + - ``COMPLEX(4) A`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DABS(A)`` + - ``REAL(8) A`` + - ``REAL(8)`` + - Fortran 77 and later + * - ``IABS(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - Fortran 77 and later + * - ``BABS(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``IIABS(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JIABS(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KIABS(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + * - ``ZABS(A)`` + - ``COMPLEX(8) A`` + - ``REAL(8)`` + - GNU extension + * - ``CDABS(A)`` + - ``COMPLEX(8) A`` + - ``REAL(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/access.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/access.rst new file mode 100644 index 0000000..8293133 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/access.rst @@ -0,0 +1,61 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ACCESS, file system, access mode + +.. _access: + +ACCESS --- Checks file access modes +*********************************** + +.. function:: ACCESS(NAME, MODE) + + ``ACCESS(NAME, MODE)`` checks whether the file :samp:`{NAME}` + exists, is readable, writable or executable. Except for the + executable check, ``ACCESS`` can be replaced by + Fortran 95's ``INQUIRE``. + + :param NAME: + Scalar ``CHARACTER`` of default kind with the + file name. Trailing blank are ignored unless the character ``achar(0)`` + is present, then all characters up to and excluding ``achar(0)`` are + used as file name. + + :param MODE: + Scalar ``CHARACTER`` of default kind with the + file access mode, may be any concatenation of ``"r"`` (readable), + ``"w"`` (writable) and ``"x"`` (executable), or ``" "`` to check + for existence. + + :return: + Returns a scalar ``INTEGER``, which is ``0`` if the file is + accessible in the given mode; otherwise or if an invalid argument + has been given for ``MODE`` the value ``1`` is returned. + + Standard: + GNU extension + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = ACCESS(NAME, MODE) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/achar.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/achar.rst new file mode 100644 index 0000000..81df133 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/achar.rst @@ -0,0 +1,56 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ACHAR, ASCII collating sequence, collating sequence, ASCII + +.. _achar: + +ACHAR --- Character in ASCII collating sequence +************************************************ + +.. function:: ACHAR(I) + + ``ACHAR(I)`` returns the character located at position ``I`` + in the ASCII collating sequence. + + :param I: + The type shall be ``INTEGER``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``CHARACTER`` with a length of one. + If the :samp:`{KIND}` argument is present, the return value is of the + specified kind and of the default kind otherwise. + + Standard: + Fortran 77 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ACHAR(I [, KIND]) + + Example: + .. code-block:: fortran + + program test_achar + character c + c = achar(32) + end program test_achar + + Note: + See :ref:`ICHAR` for a discussion of converting between numerical values + and formatted string representations. + + See also: + :ref:`CHAR`, + :ref:`IACHAR`, + :ref:`ICHAR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/acos.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/acos.rst new file mode 100644 index 0000000..f744aaf --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/acos.rst @@ -0,0 +1,73 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _acos: + +.. index:: ACOS + +.. index:: DACOS + +.. index:: trigonometric function, cosine, inverse + +.. index:: cosine, inverse + +ACOS --- Arccosine function +**************************** + +.. function:: ACOS(X) + + ``ACOS(X)`` computes the arccosine of :samp:`{X}` (inverse of ``COS(X)``). + + :param X: + The type shall either be ``REAL`` with a magnitude that is + less than or equal to one - or the type shall be ``COMPLEX``. + + :return: + The return value is of the same type and kind as :samp:`{X}`. + The real part of the result is in radians and lies in the range + 0 \leq \Re \acos(x) \leq \pi. + + Standard: + Fortran 77 and later, for a complex argument Fortran 2008 or later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ACOS(X) + + Example: + .. code-block:: fortran + + program test_acos + real(8) :: x = 0.866_8 + x = acos(x) + end program test_acos + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ACOS(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DACOS(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later + + See also: + Inverse function: + :ref:`COS` + Degrees function: + :ref:`ACOSD`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/acosd.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/acosd.rst new file mode 100644 index 0000000..676b7a4 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/acosd.rst @@ -0,0 +1,74 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _acosd: + +.. index:: ACOSD + +.. index:: DACOSD + +.. index:: trigonometric function, cosine, inverse, degrees + +.. index:: cosine, inverse, degrees + +ACOSD --- Arccosine function, degrees +************************************* + +.. function:: ACOSD(X) + + ``ACOSD(X)`` computes the arccosine of :samp:`{X}` in degrees (inverse of + ``COSD(X)``). + + :param X: + The type shall either be ``REAL`` with a magnitude that is + less than or equal to one - or the type shall be ``COMPLEX``. + + :return: + The return value is of the same type and kind as :samp:`{X}`. + The real part of the result is in degrees and lies in the range + 0 \leq \Re \acos(x) \leq 180. + + Standard: + GNU extension, enabled with :option:`-fdec-math` + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ACOSD(X) + + Example: + .. code-block:: fortran + + program test_acosd + real(8) :: x = 0.866_8 + x = acosd(x) + end program test_acosd + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ACOSD(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - GNU extension + * - ``DACOSD(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + + See also: + Inverse function: + :ref:`COSD` + Radians function: + :ref:`ACOS`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/acosh.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/acosh.rst new file mode 100644 index 0000000..b2012d1 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/acosh.rst @@ -0,0 +1,70 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _acosh: + +.. index:: ACOSH + +.. index:: DACOSH + +.. index:: area hyperbolic cosine + +.. index:: inverse hyperbolic cosine + +.. index:: hyperbolic function, cosine, inverse + +.. index:: cosine, hyperbolic, inverse + +ACOSH --- Inverse hyperbolic cosine function +******************************************** + +.. function:: ACOSH(X) + + ``ACOSH(X)`` computes the inverse hyperbolic cosine of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or ``COMPLEX``. + + :return: + The return value has the same type and kind as :samp:`{X}`. If :samp:`{X}` is + complex, the imaginary part of the result is in radians and lies between + 0 \leq \Im \acosh(x) \leq \pi. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ACOSH(X) + + Example: + .. code-block:: fortran + + PROGRAM test_acosh + REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /) + WRITE (*,*) ACOSH(x) + END PROGRAM + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DACOSH(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + + See also: + Inverse function: + :ref:`COSH`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/adjustl.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/adjustl.rst new file mode 100644 index 0000000..233516a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/adjustl.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ADJUSTL, string, adjust left, adjust string + +.. _adjustl: + +ADJUSTL --- Left adjust a string +********************************* + +.. function:: ADJUSTL(STRING) + + ``ADJUSTL(STRING)`` will left adjust a string by removing leading spaces. + Spaces are inserted at the end of the string as needed. + + :param STRING: + The type shall be ``CHARACTER``. + + :return: + The return value is of type ``CHARACTER`` and of the same kind as + :samp:`{STRING}` where leading spaces are removed and the same number of + spaces are inserted on the end of :samp:`{STRING}`. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ADJUSTL(STRING) + + Example: + .. code-block:: fortran + + program test_adjustl + character(len=20) :: str = ' gfortran' + str = adjustl(str) + print *, str + end program test_adjustl + + See also: + :ref:`ADJUSTR`, + :ref:`TRIM`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/adjustr.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/adjustr.rst new file mode 100644 index 0000000..fac4b0c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/adjustr.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ADJUSTR, string, adjust right, adjust string + +.. _adjustr: + +ADJUSTR --- Right adjust a string +********************************** + +.. function:: ADJUSTR(STRING) + + ``ADJUSTR(STRING)`` will right adjust a string by removing trailing spaces. + Spaces are inserted at the start of the string as needed. + + :param STR: + The type shall be ``CHARACTER``. + + :return: + The return value is of type ``CHARACTER`` and of the same kind as + :samp:`{STRING}` where trailing spaces are removed and the same number of + spaces are inserted at the start of :samp:`{STRING}`. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ADJUSTR(STRING) + + Example: + .. code-block:: fortran + + program test_adjustr + character(len=20) :: str = 'gfortran' + str = adjustr(str) + print *, str + end program test_adjustr + + See also: + :ref:`ADJUSTL`, + :ref:`TRIM`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/aimag.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/aimag.rst new file mode 100644 index 0000000..cf51185 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/aimag.rst @@ -0,0 +1,81 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _aimag: + +.. index:: AIMAG + +.. index:: DIMAG + +.. index:: IMAG + +.. index:: IMAGPART + +.. index:: complex numbers, imaginary part + +AIMAG --- Imaginary part of complex number +******************************************** + +.. function:: AIMAG(Z) + + ``AIMAG(Z)`` yields the imaginary part of complex argument ``Z``. + The ``IMAG(Z)`` and ``IMAGPART(Z)`` intrinsic functions are provided + for compatibility with :command:`g77`, and their use in new code is + strongly discouraged. + + :param Z: + The type of the argument shall be ``COMPLEX``. + + :return: + The return value is of type ``REAL`` with the + kind type parameter of the argument. + + Standard: + Fortran 77 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = AIMAG(Z) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``AIMAG(Z)`` + - ``COMPLEX Z`` + - ``REAL`` + - Fortran 77 and later + * - ``DIMAG(Z)`` + - ``COMPLEX(8) Z`` + - ``REAL(8)`` + - GNU extension + * - ``IMAG(Z)`` + - ``COMPLEX Z`` + - ``REAL`` + - GNU extension + * - ``IMAGPART(Z)`` + - ``COMPLEX Z`` + - ``REAL`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/aint.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/aint.rst new file mode 100644 index 0000000..2550442 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/aint.rst @@ -0,0 +1,78 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _aint: + +.. index:: AINT + +.. index:: DINT + +.. index:: floor + +.. index:: rounding, floor + +AINT --- Truncate to a whole number +*********************************** + +.. function:: AINT(A [, KIND]) + + ``AINT(A [, KIND])`` truncates its argument to a whole number. + + :param A: + The type of the argument shall be ``REAL``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``REAL`` with the kind type parameter of the + argument if the optional :samp:`{KIND}` is absent; otherwise, the kind + type parameter will be given by :samp:`{KIND}`. If the magnitude of + :samp:`{X}` is less than one, ``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 :samp:`{X}`. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = AINT(A [, KIND]) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``AINT(A)`` + - ``REAL(4) A`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DINT(A)`` + - ``REAL(8) A`` + - ``REAL(8)`` + - Fortran 77 and later
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/alarm.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/alarm.rst new file mode 100644 index 0000000..3670966 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/alarm.rst @@ -0,0 +1,59 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _alarm: + +ALARM --- Execute a routine after a given delay +*********************************************** + +.. index:: ALARM, delayed execution + +.. function:: ALARM(SECONDS, HANDLER, STATUS) + + ``ALARM(SECONDS, HANDLER [, STATUS])`` causes external subroutine :samp:`{HANDLER}` + to be executed after a delay of :samp:`{SECONDS}` by using ``alarm(2)`` to + set up a signal and ``signal(2)`` to catch it. If :samp:`{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. + + :param SECONDS: + The type of the argument shall be a scalar + ``INTEGER``. It is ``INTENT(IN)``. + + :param HANDLER: + Signal handler (``INTEGER FUNCTION`` or + ``SUBROUTINE``) or dummy/global ``INTEGER`` scalar. The scalar + values may be either ``SIG_IGN=1`` to ignore the alarm generated + or ``SIG_DFL=0`` to set the default action. It is ``INTENT(IN)``. + + :param STATUS: + (Optional) :samp:`{STATUS}` shall be a scalar + variable of the default ``INTEGER`` kind. It is ``INTENT(OUT)``. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL ALARM(SECONDS, HANDLER [, STATUS]) + + Example: + .. code-block:: fortran + + program test_alarm + external handler_print + integer i + call alarm (3, handler_print, i) + print *, i + call sleep(10) + end program test_alarm + + This will cause the external routine :samp:`{handler_print}` to be called + after 3 seconds.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/all.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/all.rst new file mode 100644 index 0000000..a023168 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/all.rst @@ -0,0 +1,61 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _all: + +ALL --- All values in MASK along DIM are true +********************************************** + +.. index:: ALL, array, apply condition, array, condition testing + +.. function:: ALL(MASK, DIM) + + ``ALL(MASK [, DIM])`` determines if all the values are true in :samp:`{MASK}` + in the array along dimension :samp:`{DIM}`. + + :param MASK: + The type of the argument shall be ``LOGICAL`` and + it shall not be scalar. + + :param DIM: + (Optional) :samp:`{DIM}` shall be a scalar integer + with a value that lies between one and the rank of :samp:`{MASK}`. + + :return: + ``ALL(MASK)`` returns a scalar value of type ``LOGICAL`` where + the kind type parameter is the same as the kind type parameter of + :samp:`{MASK}`. If :samp:`{DIM}` is present, then ``ALL(MASK, DIM)`` returns + an array with the rank of :samp:`{MASK}` minus 1. The shape is determined from + the shape of :samp:`{MASK}` where the :samp:`{DIM}` dimension is elided. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = ALL(MASK [, DIM]) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/allocated.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/allocated.rst new file mode 100644 index 0000000..eed0f76 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/allocated.rst @@ -0,0 +1,49 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ALLOCATED, allocation, status + +.. _allocated: + +ALLOCATED --- Status of an allocatable entity +********************************************* + +.. function:: ALLOCATED(ARRAY) + + ``ALLOCATED(ARRAY)`` and ``ALLOCATED(SCALAR)`` check the allocation + status of :samp:`{ARRAY}` and :samp:`{SCALAR}`, respectively. + + :param ARRAY: + The argument shall be an ``ALLOCATABLE`` array. + + :param SCALAR: + The argument shall be an ``ALLOCATABLE`` scalar. + + :return: + The return value is a scalar ``LOGICAL`` with the default logical + kind type parameter. If the argument is allocated, then the result is + ``.TRUE.`` ; otherwise, it returns ``.FALSE.`` + + Standard: + Fortran 90 and later. Note, the ``SCALAR=`` keyword and allocatable + scalar entities are available in Fortran 2003 and later. + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = ALLOCATED(ARRAY) + RESULT = ALLOCATED(SCALAR) + + Example: + .. code-block:: fortran + + program test_allocated + integer :: i = 4 + real(4), allocatable :: x(:) + if (.not. allocated(x)) allocate(x(i)) + end program test_allocated
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/and.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/and.rst new file mode 100644 index 0000000..66a8d25 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/and.rst @@ -0,0 +1,60 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _and: + +AND --- Bitwise logical AND +*************************** + +.. index:: AND, bitwise logical and, logical and, bitwise + +.. function:: AND(I, J) + + Bitwise logical ``AND``. + + :param I: + The type shall be either a scalar ``INTEGER`` + type or a scalar ``LOGICAL`` type or a boz-literal-constant. + + :param J: + The type shall be the same as the type of :samp:`{I}` or + a boz-literal-constant. :samp:`{I}` and :samp:`{J}` shall not both be + boz-literal-constants. If either :samp:`{I}` or :samp:`{J}` is a + boz-literal-constant, then the other argument must be a scalar ``INTEGER``. + + :return: + The return type is either a scalar ``INTEGER`` or a scalar + ``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 ``INTEGER`` with the kind type parameter of + the other argument as-if a call to :ref:`INT` occurred. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = AND(I, J) + + Example: + .. code-block:: fortran + + 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 + + See also: + Fortran 95 elemental function: + :ref:`IAND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/anint.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/anint.rst new file mode 100644 index 0000000..889585c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/anint.rst @@ -0,0 +1,76 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _anint: + +.. index:: ANINT + +.. index:: DNINT + +.. index:: ceiling + +.. index:: rounding, ceiling + +ANINT --- Nearest whole number +****************************** + +.. function:: ANINT(A [, KIND]) + + ``ANINT(A [, KIND])`` rounds its argument to the nearest whole number. + + :param A: + The type of the argument shall be ``REAL``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type real with the kind type parameter of the + argument if the optional :samp:`{KIND}` is absent; otherwise, the kind + type parameter will be given by :samp:`{KIND}`. If :samp:`{A}` is greater than + zero, ``ANINT(A)`` returns ``AINT(X+0.5)``. If :samp:`{A}` is + less than or equal to zero then it returns ``AINT(X-0.5)``. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ANINT(A [, KIND]) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ANINT(A)`` + - ``REAL(4) A`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DNINT(A)`` + - ``REAL(8) A`` + - ``REAL(8)`` + - Fortran 77 and later
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/any.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/any.rst new file mode 100644 index 0000000..1a2ba10 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/any.rst @@ -0,0 +1,61 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _any: + +ANY --- Any value in MASK along DIM is true +******************************************** + +.. index:: ANY, array, apply condition, array, condition testing + +.. function:: ANY(MASK, DIM) + + ``ANY(MASK [, DIM])`` determines if any of the values in the logical array + :samp:`{MASK}` along dimension :samp:`{DIM}` are ``.TRUE.``. + + :param MASK: + The type of the argument shall be ``LOGICAL`` and + it shall not be scalar. + + :param DIM: + (Optional) :samp:`{DIM}` shall be a scalar integer + with a value that lies between one and the rank of :samp:`{MASK}`. + + :return: + ``ANY(MASK)`` returns a scalar value of type ``LOGICAL`` where + the kind type parameter is the same as the kind type parameter of + :samp:`{MASK}`. If :samp:`{DIM}` is present, then ``ANY(MASK, DIM)`` returns + an array with the rank of :samp:`{MASK}` minus 1. The shape is determined from + the shape of :samp:`{MASK}` where the :samp:`{DIM}` dimension is elided. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = ANY(MASK [, DIM]) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/asin.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/asin.rst new file mode 100644 index 0000000..0b6c419 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/asin.rst @@ -0,0 +1,73 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _asin: + +.. index:: ASIN + +.. index:: DASIN + +.. index:: trigonometric function, sine, inverse + +.. index:: sine, inverse + +ASIN --- Arcsine function +************************** + +.. function:: ASIN(X) + + ``ASIN(X)`` computes the arcsine of its :samp:`{X}` (inverse of ``SIN(X)``). + + :param X: + The type shall be either ``REAL`` and a magnitude that is + less than or equal to one - or be ``COMPLEX``. + + :return: + The return value is of the same type and kind as :samp:`{X}`. + The real part of the result is in radians and lies in the range + -\pi/2 \leq \Re \asin(x) \leq \pi/2. + + Standard: + Fortran 77 and later, for a complex argument Fortran 2008 or later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ASIN(X) + + Example: + .. code-block:: fortran + + program test_asin + real(8) :: x = 0.866_8 + x = asin(x) + end program test_asin + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ASIN(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DASIN(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later + + See also: + Inverse function: + :ref:`SIN` + Degrees function: + :ref:`ASIND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/asind.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/asind.rst new file mode 100644 index 0000000..407542b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/asind.rst @@ -0,0 +1,74 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _asind: + +.. index:: ASIND + +.. index:: DASIND + +.. index:: trigonometric function, sine, inverse, degrees + +.. index:: sine, inverse, degrees + +ASIND --- Arcsine function, degrees +*********************************** + +.. function:: ASIND(X) + + ``ASIND(X)`` computes the arcsine of its :samp:`{X}` in degrees (inverse of + ``SIND(X)``). + + :param X: + The type shall be either ``REAL`` and a magnitude that is + less than or equal to one - or be ``COMPLEX``. + + :return: + The return value is of the same type and kind as :samp:`{X}`. + The real part of the result is in degrees and lies in the range + -90 \leq \Re \asin(x) \leq 90. + + Standard: + GNU extension, enabled with :option:`-fdec-math`. + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ASIND(X) + + Example: + .. code-block:: fortran + + program test_asind + real(8) :: x = 0.866_8 + x = asind(x) + end program test_asind + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ASIND(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - GNU extension + * - ``DASIND(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + + See also: + Inverse function: + :ref:`SIND` + Radians function: + :ref:`ASIN`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/asinh.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/asinh.rst new file mode 100644 index 0000000..08902e8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/asinh.rst @@ -0,0 +1,70 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _asinh: + +.. index:: ASINH + +.. index:: DASINH + +.. index:: area hyperbolic sine + +.. index:: inverse hyperbolic sine + +.. index:: hyperbolic function, sine, inverse + +.. index:: sine, hyperbolic, inverse + +ASINH --- Inverse hyperbolic sine function +****************************************** + +.. function:: ASINH(X) + + ``ASINH(X)`` computes the inverse hyperbolic sine of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or ``COMPLEX``. + + :return: + The return value is of the same type and kind as :samp:`{X}`. If :samp:`{X}` is + complex, the imaginary part of the result is in radians and lies between + -\pi/2 \leq \Im \asinh(x) \leq \pi/2. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ASINH(X) + + Example: + .. code-block:: fortran + + PROGRAM test_asinh + REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) + WRITE (*,*) ASINH(x) + END PROGRAM + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DASINH(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension. + + See also: + Inverse function: + :ref:`SINH`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/associated.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/associated.rst new file mode 100644 index 0000000..5988c21 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/associated.rst @@ -0,0 +1,74 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _associated: + +ASSOCIATED --- Status of a pointer or pointer/target pair +********************************************************** + +.. index:: ASSOCIATED, pointer, status, association status + +.. function:: ASSOCIATED(POINTER, TARGET) + + ``ASSOCIATED(POINTER [, TARGET])`` determines the status of the pointer + :samp:`{POINTER}` or if :samp:`{POINTER}` is associated with the target :samp:`{TARGET}`. + + :param POINTER: + :samp:`{POINTER}` shall have the ``POINTER`` attribute + and it can be of any type. + + :param TARGET: + (Optional) :samp:`{TARGET}` shall be a pointer or + a target. It must have the same type, kind type parameter, and + array rank as :samp:`{POINTER}`. + + :return: + ``ASSOCIATED(POINTER)`` returns a scalar value of type ``LOGICAL(4)``. + There are several cases: + + - When the optional TARGET is not present then + ASSOCIATED(POINTER) is true if POINTER is associated with a target; otherwise, it returns false. + + - If TARGET is present and a scalar target, the result is true if + TARGET is not a zero-sized storage sequence and the target associated with POINTER occupies the same storage units. If POINTER is disassociated, the result is false. + + - If TARGET is present and an array target, the result is true if + TARGET and POINTER have the same shape, are not zero-sized arrays, are arrays whose elements are not zero-sized storage sequences, + and TARGET and POINTER occupy the same storage units in array element order. As in case(B), the result is false, if POINTER is disassociated. + + - If TARGET is present and an scalar pointer, the result is true + if TARGET is associated with POINTER, the target associated with TARGET are not zero-sized storage sequences and occupy the same storage units. + The result is false, if either TARGET or POINTER is disassociated. + + - If TARGET is present and an array pointer, the result is true if + target associated with POINTER and the target associated with TARGET have the same shape, are not zero-sized arrays, + are arrays whose elements are not zero-sized storage sequences, and TARGET and POINTER occupy the same storage units in array element order. + The result is false, if either TARGET or POINTER is disassociated. + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = ASSOCIATED(POINTER [, TARGET]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`NULL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atan.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atan.rst new file mode 100644 index 0000000..ae36dda --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atan.rst @@ -0,0 +1,80 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _atan: + +.. index:: ATAN + +.. index:: DATAN + +.. index:: trigonometric function, tangent, inverse + +.. index:: tangent, inverse + +ATAN --- Arctangent function +***************************** + +.. function:: ATAN(X) + + ``ATAN(X)`` computes the arctangent of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or ``COMPLEX`` ; + if :samp:`{Y}` is present, :samp:`{X}` shall be REAL. + + :param Y: + The type and kind type parameter shall be the same as :samp:`{X}`. + + :return: + The return value is of the same type and kind as :samp:`{X}`. + If :samp:`{Y}` is present, the result is identical to ``ATAN2(Y,X)``. + Otherwise, it the arcus tangent of :samp:`{X}`, where the real part of + the result is in radians and lies in the range + -\pi/2 \leq \Re \atan(x) \leq \pi/2. + + Standard: + Fortran 77 and later, for a complex argument and for two arguments + Fortran 2008 or later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ATAN(X) + RESULT = ATAN(Y, X) + + Example: + .. code-block:: fortran + + program test_atan + real(8) :: x = 2.866_8 + x = atan(x) + end program test_atan + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ATAN(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DATAN(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later + + See also: + Inverse function: + :ref:`TAN` + Degrees function: + :ref:`ATAND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atan2.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atan2.rst new file mode 100644 index 0000000..0f61a79 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atan2.rst @@ -0,0 +1,85 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _atan2: + +.. index:: ATAN2 + +.. index:: DATAN2 + +.. index:: trigonometric function, tangent, inverse + +.. index:: tangent, inverse + +ATAN2 --- Arctangent function +****************************** + +.. function:: ATAN2(Y, X) + + ``ATAN2(Y, X)`` computes the principal value of the argument + function of the complex number 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. + + :param Y: + The type shall be ``REAL``. + + :param X: + The type and kind type parameter shall be the same as :samp:`{Y}`. + If :samp:`{Y}` is zero, then :samp:`{X}` must be nonzero. + + :return: + The return value has the same type and kind type parameter as :samp:`{Y}`. It + is the principal value of the complex number X + i Y. If :samp:`{X}` + is nonzero, then it lies in the range -\pi \le \atan (x) \leq \pi. + The sign is positive if :samp:`{Y}` is positive. If :samp:`{Y}` is zero, then + the return value is zero if :samp:`{X}` is strictly positive, \pi if + :samp:`{X}` is negative and :samp:`{Y}` is positive zero (or the processor does + not handle signed zeros), and -\pi if :samp:`{X}` is negative and + :samp:`{Y}` is negative zero. Finally, if :samp:`{X}` is zero, then the + magnitude of the result is \pi/2. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ATAN2(Y, X) + + Example: + .. code-block:: fortran + + program test_atan2 + real(4) :: x = 1.e0_4, y = 0.5e0_4 + x = atan2(y,x) + end program test_atan2 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ATAN2(X, Y)`` + - ``REAL(4) X, Y`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DATAN2(X, Y)`` + - ``REAL(8) X, Y`` + - ``REAL(8)`` + - Fortran 77 and later + + See also: + Alias: + :ref:`ATAN` + Degrees function: + :ref:`ATAN2D`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atan2d.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atan2d.rst new file mode 100644 index 0000000..1aed24a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atan2d.rst @@ -0,0 +1,85 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _atan2d: + +.. index:: ATAN2D + +.. index:: DATAN2D + +.. index:: trigonometric function, tangent, inverse, degrees + +.. index:: tangent, inverse, degrees + +ATAN2D --- Arctangent function, degrees +*************************************** + +.. function:: ATAN2D(Y, X) + + ``ATAN2D(Y, X)`` computes the principal value of the argument + function of the complex number 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. + + :param Y: + The type shall be ``REAL``. + + :param X: + The type and kind type parameter shall be the same as :samp:`{Y}`. + If :samp:`{Y}` is zero, then :samp:`{X}` must be nonzero. + + :return: + The return value has the same type and kind type parameter as :samp:`{Y}`. It + is the principal value of the complex number X + i Y. If :samp:`{X}` + is nonzero, then it lies in the range -180 \le \atan (x) \leq 180. + The sign is positive if :samp:`{Y}` is positive. If :samp:`{Y}` is zero, then + the return value is zero if :samp:`{X}` is strictly positive, 180 if + :samp:`{X}` is negative and :samp:`{Y}` is positive zero (or the processor does + not handle signed zeros), and -180 if :samp:`{X}` is negative and + :samp:`{Y}` is negative zero. Finally, if :samp:`{X}` is zero, then the + magnitude of the result is 90. + + Standard: + GNU extension, enabled with :option:`-fdec-math`. + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ATAN2D(Y, X) + + Example: + .. code-block:: fortran + + program test_atan2d + real(4) :: x = 1.e0_4, y = 0.5e0_4 + x = atan2d(y,x) + end program test_atan2d + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ATAN2D(X, Y)`` + - ``REAL(4) X, Y`` + - ``REAL(4)`` + - GNU extension + * - ``DATAN2D(X, Y)`` + - ``REAL(8) X, Y`` + - ``REAL(8)`` + - GNU extension + + See also: + Alias: + :ref:`ATAND` + Radians function: + :ref:`ATAN2`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atand.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atand.rst new file mode 100644 index 0000000..f070cfc --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atand.rst @@ -0,0 +1,80 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _atand: + +.. index:: ATAND + +.. index:: DATAND + +.. index:: trigonometric function, tangent, inverse, degrees + +.. index:: tangent, inverse, degrees + +ATAND --- Arctangent function, degrees +************************************** + +.. function:: ATAND(X) + + ``ATAND(X)`` computes the arctangent of :samp:`{X}` in degrees (inverse of + :ref:`TAND`). + + :param X: + The type shall be ``REAL`` or ``COMPLEX`` ; + if :samp:`{Y}` is present, :samp:`{X}` shall be REAL. + + :param Y: + The type and kind type parameter shall be the same as :samp:`{X}`. + + :return: + The return value is of the same type and kind as :samp:`{X}`. + If :samp:`{Y}` is present, the result is identical to ``ATAND2(Y,X)``. + Otherwise, it is the arcus tangent of :samp:`{X}`, where the real part of + the result is in degrees and lies in the range + -90 \leq \Re \atand(x) \leq 90. + + Standard: + GNU extension, enabled with :option:`-fdec-math`. + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ATAND(X) + RESULT = ATAND(Y, X) + + Example: + .. code-block:: fortran + + program test_atand + real(8) :: x = 2.866_8 + x = atand(x) + end program test_atand + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ATAND(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - GNU extension + * - ``DATAND(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + + See also: + Inverse function: + :ref:`TAND` + Radians function: + :ref:`ATAN`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atanh.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atanh.rst new file mode 100644 index 0000000..7d6f157 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atanh.rst @@ -0,0 +1,70 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _atanh: + +.. index:: ATANH + +.. index:: DATANH + +.. index:: area hyperbolic tangent + +.. index:: inverse hyperbolic tangent + +.. index:: hyperbolic function, tangent, inverse + +.. index:: tangent, hyperbolic, inverse + +ATANH --- Inverse hyperbolic tangent function +********************************************* + +.. function:: ATANH(X) + + ``ATANH(X)`` computes the inverse hyperbolic tangent of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`. If :samp:`{X}` is + complex, the imaginary part of the result is in radians and lies between + -\pi/2 \leq \Im \atanh(x) \leq \pi/2. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ATANH(X) + + Example: + .. code-block:: fortran + + PROGRAM test_atanh + REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) + WRITE (*,*) ATANH(x) + END PROGRAM + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DATANH(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + + See also: + Inverse function: + :ref:`TANH`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicadd.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicadd.rst new file mode 100644 index 0000000..3b1195e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicadd.rst @@ -0,0 +1,60 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ATOMIC_ADD, Atomic subroutine, add + +.. _atomic_add: + +ATOMIC_ADD --- Atomic ADD operation +*********************************** + +.. function:: ATOMIC_ADD(ATOM, VALUE) + + ``ATOMIC_ADD(ATOM, VALUE)`` atomically adds the value of :samp:`{VALUE}` to the + variable :samp:`{ATOM}`. When :samp:`{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 + :samp:`{ATOM}`, if the remote image has stopped, it is assigned the value of + ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote image has + failed, the value ``STAT_FAILED_IMAGE``. + + :param ATOM: + Scalar coarray or coindexed variable of integer + type with ``ATOMIC_INT_KIND`` kind. + + :param VALUE: + Scalar of the same type as :samp:`{ATOM}`. If the kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_ADD (ATOM, VALUE [, STAT]) + + Example: + .. code-block:: fortran + + program atomic + use iso_fortran_env + integer(atomic_int_kind) :: atom[*] + call atomic_add (atom[1], this_image()) + end program atomic + + See also: + :ref:`ATOMIC_DEFINE`, + :ref:`ATOMIC_FETCH_ADD`, + :ref:`ISO_FORTRAN_ENV`, + :ref:`ATOMIC_AND`, + :ref:`ATOMIC_OR`, + :ref:`ATOMIC_XOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicand.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicand.rst new file mode 100644 index 0000000..fd503c8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicand.rst @@ -0,0 +1,60 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ATOMIC_AND, Atomic subroutine, AND + +.. _atomic_and: + +ATOMIC_AND --- Atomic bitwise AND operation +******************************************* + +.. function:: ATOMIC_AND(ATOM, VALUE) + + ``ATOMIC_AND(ATOM, VALUE)`` atomically defines :samp:`{ATOM}` with the bitwise + AND between the values of :samp:`{ATOM}` and :samp:`{VALUE}`. When :samp:`{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 :samp:`{ATOM}`, if the remote image has stopped, it is assigned the + value of ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote + image has failed, the value ``STAT_FAILED_IMAGE``. + + :param ATOM: + Scalar coarray or coindexed variable of integer + type with ``ATOMIC_INT_KIND`` kind. + + :param VALUE: + Scalar of the same type as :samp:`{ATOM}`. If the kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_AND (ATOM, VALUE [, STAT]) + + Example: + .. code-block:: fortran + + program atomic + use iso_fortran_env + integer(atomic_int_kind) :: atom[*] + call atomic_and (atom[1], int(b'10100011101')) + end program atomic + + See also: + :ref:`ATOMIC_DEFINE`, + :ref:`ATOMIC_FETCH_AND`, + :ref:`ISO_FORTRAN_ENV`, + :ref:`ATOMIC_ADD`, + :ref:`ATOMIC_OR`, + :ref:`ATOMIC_XOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomiccas.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomiccas.rst new file mode 100644 index 0000000..a26e134 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomiccas.rst @@ -0,0 +1,67 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _atomic_cas: + +ATOMIC_CAS --- Atomic compare and swap +************************************** + +.. index:: ATOMIC_DEFINE, Atomic subroutine, compare and swap + +.. function:: ATOMIC_CAS(ATOM, OLD, COMPARE, NEW, STAT) + + ``ATOMIC_CAS`` compares the variable :samp:`{ATOM}` with the value of + :samp:`{COMPARE}` ; if the value is the same, :samp:`{ATOM}` is set to the value + of :samp:`{NEW}`. Additionally, :samp:`{OLD}` is set to the value of :samp:`{ATOM}` + that was used for the comparison. When :samp:`{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 + :samp:`{ATOM}`, if the remote image has stopped, it is assigned the value of + ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote image has + failed, the value ``STAT_FAILED_IMAGE``. + + :param ATOM: + Scalar coarray or coindexed variable of either integer + type with ``ATOMIC_INT_KIND`` kind or logical type with + ``ATOMIC_LOGICAL_KIND`` kind. + + :param OLD: + Scalar of the same type and kind as :samp:`{ATOM}`. + + :param COMPARE: + Scalar variable of the same type and kind as + :samp:`{ATOM}`. + + :param NEW: + Scalar variable of the same type as :samp:`{ATOM}`. If kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT]) + + Example: + .. code-block:: fortran + + program atomic + use iso_fortran_env + logical(atomic_logical_kind) :: atom[*], prev + call atomic_cas (atom[1], prev, .false., .true.)) + end program atomic + + See also: + :ref:`ATOMIC_DEFINE`, + :ref:`ATOMIC_REF`, + :ref:`ISO_FORTRAN_ENV`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicdefine.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicdefine.rst new file mode 100644 index 0000000..4366028 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicdefine.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ATOMIC_DEFINE, Atomic subroutine, define + +.. _atomic_define: + +ATOMIC_DEFINE --- Setting a variable atomically +*********************************************** + +.. function:: ATOMIC_DEFINE(ATOM, VALUE) + + ``ATOMIC_DEFINE(ATOM, VALUE)`` defines the variable :samp:`{ATOM}` with the value + :samp:`{VALUE}` atomically. When :samp:`{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 + :samp:`{ATOM}`, if the remote image has stopped, it is assigned the value of + ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote image has + failed, the value ``STAT_FAILED_IMAGE``. + + :param ATOM: + Scalar coarray or coindexed variable of either integer + type with ``ATOMIC_INT_KIND`` kind or logical type with + ``ATOMIC_LOGICAL_KIND`` kind. + + :param VALUE: + Scalar of the same type as :samp:`{ATOM}`. If the kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + Fortran 2008 and later; with :samp:`{STAT}`, TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT]) + + Example: + .. code-block:: fortran + + program atomic + use iso_fortran_env + integer(atomic_int_kind) :: atom[*] + call atomic_define (atom[1], this_image()) + end program atomic + + See also: + :ref:`ATOMIC_REF`, + :ref:`ATOMIC_CAS`, + :ref:`ISO_FORTRAN_ENV`, + :ref:`ATOMIC_ADD`, + :ref:`ATOMIC_AND`, + :ref:`ATOMIC_OR`, + :ref:`ATOMIC_XOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchadd.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchadd.rst new file mode 100644 index 0000000..a3b1059 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchadd.rst @@ -0,0 +1,65 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ATOMIC_FETCH_ADD, Atomic subroutine, ADD with fetch + +.. _atomic_fetch_add: + +ATOMIC_FETCH_ADD --- Atomic ADD operation with prior fetch +********************************************************** + +.. function:: ATOMIC_FETCH_ADD(ATOM, VALUE, OLD) + + ``ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)`` atomically stores the value of + :samp:`{ATOM}` in :samp:`{OLD}` and adds the value of :samp:`{VALUE}` to the + variable :samp:`{ATOM}`. When :samp:`{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 + :samp:`{ATOM}`, if the remote image has stopped, it is assigned the value of + ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote image has + failed, the value ``STAT_FAILED_IMAGE``. + + :param ATOM: + Scalar coarray or coindexed variable of integer + type with ``ATOMIC_INT_KIND`` kind. + ``ATOMIC_LOGICAL_KIND`` kind. + + :param VALUE: + Scalar of the same type as :samp:`{ATOM}`. If the kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param OLD: + Scalar of the same type and kind as :samp:`{ATOM}`. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT]) + + Example: + .. code-block:: fortran + + program atomic + use iso_fortran_env + integer(atomic_int_kind) :: atom[*], old + call atomic_add (atom[1], this_image(), old) + end program atomic + + See also: + :ref:`ATOMIC_DEFINE`, + :ref:`ATOMIC_ADD`, + :ref:`ISO_FORTRAN_ENV`, + :ref:`ATOMIC_FETCH_AND`, + :ref:`ATOMIC_FETCH_OR`, + :ref:`ATOMIC_FETCH_XOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchand.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchand.rst new file mode 100644 index 0000000..379a767 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchand.rst @@ -0,0 +1,64 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ATOMIC_FETCH_AND, Atomic subroutine, AND with fetch + +.. _atomic_fetch_and: + +ATOMIC_FETCH_AND --- Atomic bitwise AND operation with prior fetch +****************************************************************** + +.. function:: ATOMIC_FETCH_AND (ATOM, VALUE, OLD , STAT) + + ``ATOMIC_AND(ATOM, VALUE)`` atomically stores the value of :samp:`{ATOM}` in + :samp:`{OLD}` and defines :samp:`{ATOM}` with the bitwise AND between the values of + :samp:`{ATOM}` and :samp:`{VALUE}`. When :samp:`{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 + :samp:`{ATOM}`, if the remote image has stopped, it is assigned the value of + ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote image has + failed, the value ``STAT_FAILED_IMAGE``. + + :param ATOM: + Scalar coarray or coindexed variable of integer + type with ``ATOMIC_INT_KIND`` kind. + + :param VALUE: + Scalar of the same type as :samp:`{ATOM}`. If the kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param OLD: + Scalar of the same type and kind as :samp:`{ATOM}`. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`ATOMIC_DEFINE`, + :ref:`ATOMIC_AND`, + :ref:`ISO_FORTRAN_ENV`, + :ref:`ATOMIC_FETCH_ADD`, + :ref:`ATOMIC_FETCH_OR`, + :ref:`ATOMIC_FETCH_XOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchor.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchor.rst new file mode 100644 index 0000000..5dd5391 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchor.rst @@ -0,0 +1,64 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ATOMIC_FETCH_OR, Atomic subroutine, OR with fetch + +.. _atomic_fetch_or: + +ATOMIC_FETCH_OR --- Atomic bitwise OR operation with prior fetch +**************************************************************** + +.. function:: ATOMIC_FETCH_OR (ATOM, VALUE, OLD , STAT) + + ``ATOMIC_OR(ATOM, VALUE)`` atomically stores the value of :samp:`{ATOM}` in + :samp:`{OLD}` and defines :samp:`{ATOM}` with the bitwise OR between the values of + :samp:`{ATOM}` and :samp:`{VALUE}`. When :samp:`{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 + :samp:`{ATOM}`, if the remote image has stopped, it is assigned the value of + ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote image has + failed, the value ``STAT_FAILED_IMAGE``. + + :param ATOM: + Scalar coarray or coindexed variable of integer + type with ``ATOMIC_INT_KIND`` kind. + + :param VALUE: + Scalar of the same type as :samp:`{ATOM}`. If the kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param OLD: + Scalar of the same type and kind as :samp:`{ATOM}`. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`ATOMIC_DEFINE`, + :ref:`ATOMIC_OR`, + :ref:`ISO_FORTRAN_ENV`, + :ref:`ATOMIC_FETCH_ADD`, + :ref:`ATOMIC_FETCH_AND`, + :ref:`ATOMIC_FETCH_XOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchxor.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchxor.rst new file mode 100644 index 0000000..4f5a4c2 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicfetchxor.rst @@ -0,0 +1,64 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ATOMIC_FETCH_XOR, Atomic subroutine, XOR with fetch + +.. _atomic_fetch_xor: + +ATOMIC_FETCH_XOR --- Atomic bitwise XOR operation with prior fetch +****************************************************************** + +.. function:: ATOMIC_FETCH_XOR (ATOM, VALUE, OLD , STAT) + + ``ATOMIC_XOR(ATOM, VALUE)`` atomically stores the value of :samp:`{ATOM}` in + :samp:`{OLD}` and defines :samp:`{ATOM}` with the bitwise XOR between the values of + :samp:`{ATOM}` and :samp:`{VALUE}`. When :samp:`{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 + :samp:`{ATOM}`, if the remote image has stopped, it is assigned the value of + ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote image has + failed, the value ``STAT_FAILED_IMAGE``. + + :param ATOM: + Scalar coarray or coindexed variable of integer + type with ``ATOMIC_INT_KIND`` kind. + + :param VALUE: + Scalar of the same type as :samp:`{ATOM}`. If the kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param OLD: + Scalar of the same type and kind as :samp:`{ATOM}`. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`ATOMIC_DEFINE`, + :ref:`ATOMIC_XOR`, + :ref:`ISO_FORTRAN_ENV`, + :ref:`ATOMIC_FETCH_ADD`, + :ref:`ATOMIC_FETCH_AND`, + :ref:`ATOMIC_FETCH_OR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicor.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicor.rst new file mode 100644 index 0000000..ed5ae9c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicor.rst @@ -0,0 +1,60 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ATOMIC_OR, Atomic subroutine, OR + +.. _atomic_or: + +ATOMIC_OR --- Atomic bitwise OR operation +***************************************** + +.. function:: ATOMIC_OR(ATOM, VALUE) + + ``ATOMIC_OR(ATOM, VALUE)`` atomically defines :samp:`{ATOM}` with the bitwise + AND between the values of :samp:`{ATOM}` and :samp:`{VALUE}`. When :samp:`{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 :samp:`{ATOM}`, if the remote image has stopped, it is assigned the + value of ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote + image has failed, the value ``STAT_FAILED_IMAGE``. + + :param ATOM: + Scalar coarray or coindexed variable of integer + type with ``ATOMIC_INT_KIND`` kind. + + :param VALUE: + Scalar of the same type as :samp:`{ATOM}`. If the kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_OR (ATOM, VALUE [, STAT]) + + Example: + .. code-block:: fortran + + program atomic + use iso_fortran_env + integer(atomic_int_kind) :: atom[*] + call atomic_or (atom[1], int(b'10100011101')) + end program atomic + + See also: + :ref:`ATOMIC_DEFINE`, + :ref:`ATOMIC_FETCH_OR`, + :ref:`ISO_FORTRAN_ENV`, + :ref:`ATOMIC_ADD`, + :ref:`ATOMIC_OR`, + :ref:`ATOMIC_XOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicref.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicref.rst new file mode 100644 index 0000000..2bbae37 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicref.rst @@ -0,0 +1,68 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ATOMIC_REF, Atomic subroutine, reference + +.. _atomic_ref: + +ATOMIC_REF --- Obtaining the value of a variable atomically +*********************************************************** + +.. function:: ATOMIC_REF(VALUE, ATOM , STAT) + + ``ATOMIC_DEFINE(ATOM, VALUE)`` atomically assigns the value of the + variable :samp:`{ATOM}` to :samp:`{VALUE}`. When :samp:`{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 :samp:`{ATOM}`, if the remote image has stopped, it is assigned the value + of ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote image + has failed, the value ``STAT_FAILED_IMAGE``. + + :param VALUE: + Scalar of the same type as :samp:`{ATOM}`. If the kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param ATOM: + Scalar coarray or coindexed variable of either integer + type with ``ATOMIC_INT_KIND`` kind or logical type with + ``ATOMIC_LOGICAL_KIND`` kind. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + Fortran 2008 and later; with :samp:`{STAT}`, TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_REF(VALUE, ATOM [, STAT]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`ATOMIC_DEFINE`, + :ref:`ATOMIC_CAS`, + :ref:`ISO_FORTRAN_ENV`, + :ref:`ATOMIC_FETCH_ADD`, + :ref:`ATOMIC_FETCH_AND`, + :ref:`ATOMIC_FETCH_OR`, + :ref:`ATOMIC_FETCH_XOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicxor.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicxor.rst new file mode 100644 index 0000000..7e4a38b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/atomicxor.rst @@ -0,0 +1,60 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ATOMIC_XOR, Atomic subroutine, XOR + +.. _atomic_xor: + +ATOMIC_XOR --- Atomic bitwise OR operation +****************************************** + +.. function:: ATOMIC_XOR (ATOM, VALUE , STAT) + + ``ATOMIC_AND(ATOM, VALUE)`` atomically defines :samp:`{ATOM}` with the bitwise + XOR between the values of :samp:`{ATOM}` and :samp:`{VALUE}`. When :samp:`{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 :samp:`{ATOM}`, if the remote image has stopped, it is assigned the + value of ``ISO_FORTRAN_ENV`` 's ``STAT_STOPPED_IMAGE`` and if the remote + image has failed, the value ``STAT_FAILED_IMAGE``. + + :param ATOM: + Scalar coarray or coindexed variable of integer + type with ``ATOMIC_INT_KIND`` kind. + + :param VALUE: + Scalar of the same type as :samp:`{ATOM}`. If the kind + is different, the value is converted to the kind of :samp:`{ATOM}`. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + TS 18508 or later + + Class: + Atomic subroutine + + Syntax: + .. code-block:: fortran + + CALL ATOMIC_XOR (ATOM, VALUE [, STAT]) + + Example: + .. code-block:: fortran + + program atomic + use iso_fortran_env + integer(atomic_int_kind) :: atom[*] + call atomic_xor (atom[1], int(b'10100011101')) + end program atomic + + See also: + :ref:`ATOMIC_DEFINE`, + :ref:`ATOMIC_FETCH_XOR`, + :ref:`ISO_FORTRAN_ENV`, + :ref:`ATOMIC_ADD`, + :ref:`ATOMIC_OR`, + :ref:`ATOMIC_XOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/backtrace.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/backtrace.rst new file mode 100644 index 0000000..04b0854 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/backtrace.rst @@ -0,0 +1,34 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _backtrace: + +BACKTRACE --- Show a backtrace +****************************** + +.. index:: BACKTRACE, backtrace + +.. function:: BACKTRACE() + + ``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 ``ERROR_UNIT`` in ``ISO_FORTRAN_ENV``. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL BACKTRACE + + Arguments: + None + + See also: + :ref:`ABORT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/besselj0.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/besselj0.rst new file mode 100644 index 0000000..5317b76 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/besselj0.rst @@ -0,0 +1,64 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _bessel_j0: + +.. index:: BESSEL_J0 + +.. index:: BESJ0 + +.. index:: DBESJ0 + +.. index:: Bessel function, first kind + +BESSEL_J0 --- Bessel function of the first kind of order 0 +********************************************************** + +.. function:: BESSEL_J0(X) + + ``BESSEL_J0(X)`` computes the Bessel function of the first kind of + order 0 of :samp:`{X}`. This function is available under the name + ``BESJ0`` as a GNU extension. + + :param X: + The type shall be ``REAL``. + + :return: + The return value is of type ``REAL`` and lies in the + range - 0.4027... \leq Bessel (0,x) \leq 1. It has the same + kind as :samp:`{X}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = BESSEL_J0(X) + + Example: + .. code-block:: fortran + + program test_besj0 + real(8) :: x = 0.0_8 + x = bessel_j0(x) + end program test_besj0 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DBESJ0(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/besselj1.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/besselj1.rst new file mode 100644 index 0000000..973c387 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/besselj1.rst @@ -0,0 +1,64 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _bessel_j1: + +.. index:: BESSEL_J1 + +.. index:: BESJ1 + +.. index:: DBESJ1 + +.. index:: Bessel function, first kind + +BESSEL_J1 --- Bessel function of the first kind of order 1 +********************************************************** + +.. function:: BESSEL_J1(X) + + ``BESSEL_J1(X)`` computes the Bessel function of the first kind of + order 1 of :samp:`{X}`. This function is available under the name + ``BESJ1`` as a GNU extension. + + :param X: + The type shall be ``REAL``. + + :return: + The return value is of type ``REAL`` and lies in the + range - 0.5818... \leq Bessel (0,x) \leq 0.5818 . It has the same + kind as :samp:`{X}`. + + Standard: + Fortran 2008 + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = BESSEL_J1(X) + + Example: + .. code-block:: fortran + + program test_besj1 + real(8) :: x = 1.0_8 + x = bessel_j1(x) + end program test_besj1 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DBESJ1(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/besseljn.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/besseljn.rst new file mode 100644 index 0000000..75efb2b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/besseljn.rst @@ -0,0 +1,85 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _bessel_jn: + +.. index:: BESSEL_JN + +.. index:: BESJN + +.. index:: DBESJN + +.. index:: Bessel function, first kind + +BESSEL_JN --- Bessel function of the first kind +*********************************************** + +.. function:: BESSEL_JN(N, X) + + ``BESSEL_JN(N, X)`` computes the Bessel function of the first kind of + order :samp:`{N}` of :samp:`{X}`. This function is available under the name + ``BESJN`` as a GNU extension. If :samp:`{N}` and :samp:`{X}` are arrays, + their ranks and shapes shall conform. + + :param N: + Shall be a scalar or an array of type ``INTEGER``. + + :param N1: + Shall be a non-negative scalar of type ``INTEGER``. + + :param N2: + Shall be a non-negative scalar of type ``INTEGER``. + + :param X: + Shall be a scalar or an array of type ``REAL`` ; + for ``BESSEL_JN(N1, N2, X)`` it shall be scalar. + + :return: + The return value is a scalar of type ``REAL``. It has the same + kind as :samp:`{X}`. + + Standard: + Fortran 2008 and later, negative :samp:`{N}` is allowed as GNU extension + + Class: + Elemental function, except for the transformational function + ``BESSEL_JN(N1, N2, X)`` + + Syntax: + .. code-block:: fortran + + RESULT = BESSEL_JN(N, X) + RESULT = BESSEL_JN(N1, N2, X) + + Note: + The transformational function uses a recurrence algorithm which might, + for some values of :samp:`{X}`, lead to different results than calls to + the elemental function. + + Example: + .. code-block:: fortran + + program test_besjn + real(8) :: x = 1.0_8 + x = bessel_jn(5,x) + end program test_besjn + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DBESJN(N, X)`` + - ``INTEGER N`` + - ``REAL(8)`` + - GNU extension + * - + - ``REAL(8) X`` + - + -
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/bessely0.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/bessely0.rst new file mode 100644 index 0000000..455ba64 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/bessely0.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _bessel_y0: + +.. index:: BESSEL_Y0 + +.. index:: BESY0 + +.. index:: DBESY0 + +.. index:: Bessel function, second kind + +BESSEL_Y0 --- Bessel function of the second kind of order 0 +*********************************************************** + +.. function:: BESSEL_Y0(X) + + ``BESSEL_Y0(X)`` computes the Bessel function of the second kind of + order 0 of :samp:`{X}`. This function is available under the name + ``BESY0`` as a GNU extension. + + :param X: + The type shall be ``REAL``. + + :return: + The return value is of type ``REAL``. It has the same kind as :samp:`{X}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = BESSEL_Y0(X) + + Example: + .. code-block:: fortran + + program test_besy0 + real(8) :: x = 0.0_8 + x = bessel_y0(x) + end program test_besy0 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DBESY0(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/bessely1.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/bessely1.rst new file mode 100644 index 0000000..e1f26af --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/bessely1.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _bessel_y1: + +.. index:: BESSEL_Y1 + +.. index:: BESY1 + +.. index:: DBESY1 + +.. index:: Bessel function, second kind + +BESSEL_Y1 --- Bessel function of the second kind of order 1 +*********************************************************** + +.. function:: BESSEL_Y1(X) + + ``BESSEL_Y1(X)`` computes the Bessel function of the second kind of + order 1 of :samp:`{X}`. This function is available under the name + ``BESY1`` as a GNU extension. + + :param X: + The type shall be ``REAL``. + + :return: + The return value is of type ``REAL``. It has the same kind as :samp:`{X}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = BESSEL_Y1(X) + + Example: + .. code-block:: fortran + + program test_besy1 + real(8) :: x = 1.0_8 + x = bessel_y1(x) + end program test_besy1 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DBESY1(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/besselyn.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/besselyn.rst new file mode 100644 index 0000000..2a0556e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/besselyn.rst @@ -0,0 +1,85 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _bessel_yn: + +.. index:: BESSEL_YN + +.. index:: BESYN + +.. index:: DBESYN + +.. index:: Bessel function, second kind + +BESSEL_YN --- Bessel function of the second kind +************************************************ + +.. function:: BESSEL_YN(N, X) + + ``BESSEL_YN(N, X)`` computes the Bessel function of the second kind of + order :samp:`{N}` of :samp:`{X}`. This function is available under the name + ``BESYN`` as a GNU extension. If :samp:`{N}` and :samp:`{X}` are arrays, + their ranks and shapes shall conform. + + :param N: + Shall be a scalar or an array of type ``INTEGER`` . + + :param N1: + Shall be a non-negative scalar of type ``INTEGER``. + + :param N2: + Shall be a non-negative scalar of type ``INTEGER``. + + :param X: + Shall be a scalar or an array of type ``REAL`` ; + for ``BESSEL_YN(N1, N2, X)`` it shall be scalar. + + :return: + The return value is a scalar of type ``REAL``. It has the same + kind as :samp:`{X}`. + + Standard: + Fortran 2008 and later, negative :samp:`{N}` is allowed as GNU extension + + Class: + Elemental function, except for the transformational function + ``BESSEL_YN(N1, N2, X)`` + + Syntax: + .. code-block:: fortran + + RESULT = BESSEL_YN(N, X) + RESULT = BESSEL_YN(N1, N2, X) + + Note: + The transformational function uses a recurrence algorithm which might, + for some values of :samp:`{X}`, lead to different results than calls to + the elemental function. + + Example: + .. code-block:: fortran + + program test_besyn + real(8) :: x = 1.0_8 + x = bessel_yn(5,x) + end program test_besyn + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DBESYN(N,X)`` + - ``INTEGER N`` + - ``REAL(8)`` + - GNU extension + * - + - ``REAL(8) X`` + - + -
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/bge.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/bge.rst new file mode 100644 index 0000000..0b53692 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/bge.rst @@ -0,0 +1,42 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: BGE, bitwise comparison + +.. _bge: + +BGE --- Bitwise greater than or equal to +**************************************** + +.. function:: BGE(I, J) + + Determines whether an integral is a bitwise greater than or equal to + another. + + :param I: + Shall be of ``INTEGER`` type. + + :param J: + Shall be of ``INTEGER`` type, and of the same kind + as :samp:`{I}`. + + :return: + The return value is of type ``LOGICAL`` and of the default kind. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = BGE(I, J) + + See also: + :ref:`BGT`, + :ref:`BLE`, + :ref:`BLT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/bgt.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/bgt.rst new file mode 100644 index 0000000..b033ef5 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/bgt.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: BGT, bitwise comparison + +.. _bgt: + +BGT --- Bitwise greater than +**************************** + +.. function:: BGT(I, J) + + Determines whether an integral is a bitwise greater than another. + + :param I: + Shall be of ``INTEGER`` type. + + :param J: + Shall be of ``INTEGER`` type, and of the same kind + as :samp:`{I}`. + + :return: + The return value is of type ``LOGICAL`` and of the default kind. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = BGT(I, J) + + See also: + :ref:`BGE`, + :ref:`BLE`, + :ref:`BLT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/bitsize.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/bitsize.rst new file mode 100644 index 0000000..2aac37c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/bitsize.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: BIT_SIZE, bits, number of, size of a variable, in bits + +.. _bit_size: + +BIT_SIZE --- Bit size inquiry function +************************************** + +.. function:: BIT_SIZE(I) + + ``BIT_SIZE(I)`` returns the number of bits (integer precision plus sign bit) + represented by the type of :samp:`{I}`. The result of ``BIT_SIZE(I)`` is + independent of the actual value of :samp:`{I}`. + + :param I: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = BIT_SIZE(I) + + Example: + .. code-block:: fortran + + program test_bit_size + integer :: i = 123 + integer :: size + size = bit_size(i) + print *, size + end program test_bit_size
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ble.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ble.rst new file mode 100644 index 0000000..5144446 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ble.rst @@ -0,0 +1,42 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: BLE, bitwise comparison + +.. _ble: + +BLE --- Bitwise less than or equal to +************************************* + +.. function:: BLE(I, J) + + Determines whether an integral is a bitwise less than or equal to + another. + + :param I: + Shall be of ``INTEGER`` type. + + :param J: + Shall be of ``INTEGER`` type, and of the same kind + as :samp:`{I}`. + + :return: + The return value is of type ``LOGICAL`` and of the default kind. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = BLE(I, J) + + See also: + :ref:`BGT`, + :ref:`BGE`, + :ref:`BLT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/blt.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/blt.rst new file mode 100644 index 0000000..225f63f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/blt.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: BLT, bitwise comparison + +.. _blt: + +BLT --- Bitwise less than +************************* + +.. function:: BLT(I, J) + + Determines whether an integral is a bitwise less than another. + + :param I: + Shall be of ``INTEGER`` type. + + :param J: + Shall be of ``INTEGER`` type, and of the same kind + as :samp:`{I}`. + + :return: + The return value is of type ``LOGICAL`` and of the default kind. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = BLT(I, J) + + See also: + :ref:`BGE`, + :ref:`BGT`, + :ref:`BLE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/btest.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/btest.rst new file mode 100644 index 0000000..c0f9c91 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/btest.rst @@ -0,0 +1,89 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _btest: + +.. index:: BTEST + +.. index:: BBTEST + +.. index:: BITEST + +.. index:: BJTEST + +.. index:: BKTEST + +.. index:: bits, testing + +BTEST --- Bit test function +*************************** + +.. function:: BTEST(I,POS) + + ``BTEST(I,POS)`` returns logical ``.TRUE.`` if the bit at :samp:`{POS}` + in :samp:`{I}` is set. The counting of the bits starts at 0. + + :param I: + The type shall be ``INTEGER``. + + :param POS: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``LOGICAL`` + + Standard: + Fortran 90 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = BTEST(I, POS) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``BTEST(I,POS)`` + - ``INTEGER I,POS`` + - ``LOGICAL`` + - Fortran 95 and later + * - ``BBTEST(I,POS)`` + - ``INTEGER(1) I,POS`` + - ``LOGICAL(1)`` + - GNU extension + * - ``BITEST(I,POS)`` + - ``INTEGER(2) I,POS`` + - ``LOGICAL(2)`` + - GNU extension + * - ``BJTEST(I,POS)`` + - ``INTEGER(4) I,POS`` + - ``LOGICAL(4)`` + - GNU extension + * - ``BKTEST(I,POS)`` + - ``INTEGER(8) I,POS`` + - ``LOGICAL(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cassociated.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cassociated.rst new file mode 100644 index 0000000..a42c04d --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cassociated.rst @@ -0,0 +1,54 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _c_associated: + +C_ASSOCIATED --- Status of a C pointer +************************************** + +.. index:: C_ASSOCIATED, association status, C pointer, pointer, C association status + +.. function:: C_ASSOCIATED(c_ptr_1, c_ptr_2) + + ``C_ASSOCIATED(c_ptr_1[, c_ptr_2])`` determines the status of the C pointer + :samp:`{c_ptr_1}` or if :samp:`{c_ptr_1}` is associated with the target :samp:`{c_ptr_2}`. + + :param c_ptr_1: + Scalar of the type ``C_PTR`` or ``C_FUNPTR``. + + :param c_ptr_2: + (Optional) Scalar of the same type as :samp:`{c_ptr_1}`. + + :return: + The return value is of type ``LOGICAL`` ; it is ``.false.`` if either + :samp:`{c_ptr_1}` is a C NULL pointer or if :samp:`{c_ptr1}` and :samp:`{c_ptr_2}` + point to different addresses. + + Standard: + Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`C_LOC`, + :ref:`C_FUNLOC`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ceiling.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ceiling.rst new file mode 100644 index 0000000..de9e211 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ceiling.rst @@ -0,0 +1,51 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: CEILING, ceiling, rounding, ceiling + +.. _ceiling: + +CEILING --- Integer ceiling function +************************************ + +.. function:: CEILING(A) + + ``CEILING(A)`` returns the least integer greater than or equal to :samp:`{A}`. + + :param A: + The type shall be ``REAL``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER(KIND)`` if :samp:`{KIND}` is present + and a default-kind ``INTEGER`` otherwise. + + Standard: + Fortran 95 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = CEILING(A [, KIND]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`FLOOR`, + :ref:`NINT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cfpointer.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cfpointer.rst new file mode 100644 index 0000000..2d60e2c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cfpointer.rst @@ -0,0 +1,63 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _c_f_pointer: + +C_F_POINTER --- Convert C into Fortran pointer +********************************************** + +.. index:: C_F_POINTER, pointer, convert C to Fortran + +.. function:: C_F_POINTER(CPTR, FPTR, SHAPE) + + ``C_F_POINTER(CPTR, FPTR[, SHAPE])`` assigns the target of the C pointer + :samp:`{CPTR}` to the Fortran pointer :samp:`{FPTR}` and specifies its shape. + + :param CPTR: + scalar of the type ``C_PTR``. It is + ``INTENT(IN)``. + + :param FPTR: + pointer interoperable with :samp:`{cptr}`. It is + ``INTENT(OUT)``. + + :param SHAPE: + (Optional) Rank-one array of type ``INTEGER`` + with ``INTENT(IN)``. It shall be present + if and only if :samp:`{fptr}` is an array. The size + must be equal to the rank of :samp:`{fptr}`. + + Standard: + Fortran 2003 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL C_F_POINTER(CPTR, FPTR[, SHAPE]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`C_LOC`, + :ref:`C_F_PROCPOINTER`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cfprocpointer.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cfprocpointer.rst new file mode 100644 index 0000000..2dedd69 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cfprocpointer.rst @@ -0,0 +1,64 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: C_F_PROCPOINTER, pointer, C address of pointers + +.. _c_f_procpointer: + +C_F_PROCPOINTER --- Convert C into Fortran procedure pointer +************************************************************ + +.. function:: C_F_PROCPOINTER(CPTR, FPTR) + + ``C_F_PROCPOINTER(CPTR, FPTR)`` Assign the target of the C function pointer + :samp:`{CPTR}` to the Fortran procedure pointer :samp:`{FPTR}`. + + :param CPTR: + scalar of the type ``C_FUNPTR``. It is + ``INTENT(IN)``. + + :param FPTR: + procedure pointer interoperable with :samp:`{cptr}`. It is + ``INTENT(OUT)``. + + Standard: + Fortran 2003 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL C_F_PROCPOINTER(cptr, fptr) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`C_LOC`, + :ref:`C_F_POINTER`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cfunloc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cfunloc.rst new file mode 100644 index 0000000..19c8c19 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cfunloc.rst @@ -0,0 +1,64 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: C_FUNLOC, pointer, C address of procedures + +.. _c_funloc: + +C_FUNLOC --- Obtain the C address of a procedure +************************************************ + +.. function:: C_FUNLOC(x) + + ``C_FUNLOC(x)`` determines the C address of the argument. + + :param x: + Interoperable function or pointer to such function. + + :return: + The return value is of type ``C_FUNPTR`` and contains the C address + of the argument. + + Standard: + Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = C_FUNLOC(x) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`C_ASSOCIATED`, + :ref:`C_LOC`, + :ref:`C_F_POINTER`, + :ref:`C_F_PROCPOINTER`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/char.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/char.rst new file mode 100644 index 0000000..221deca --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/char.rst @@ -0,0 +1,71 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _char: + +.. index:: CHAR + +.. index:: conversion, to character + +CHAR --- Character conversion function +************************************** + +.. function:: CHAR(I [, KIND]) + + ``CHAR(I [, KIND])`` returns the character represented by the integer :samp:`{I}`. + + :param I: + The type shall be ``INTEGER``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``CHARACTER(1)`` + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = CHAR(I [, KIND]) + + Example: + .. code-block:: fortran + + program test_char + integer :: i = 74 + character(1) :: c + c = char(i) + print *, i, c ! returns 'J' + end program test_char + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``CHAR(I)`` + - ``INTEGER I`` + - ``CHARACTER(LEN=1)`` + - Fortran 77 and later + + Note: + See :ref:`ICHAR` for a discussion of converting between numerical values + and formatted string representations. + + See also: + :ref:`ACHAR`, + :ref:`IACHAR`, + :ref:`ICHAR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/chdir.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/chdir.rst new file mode 100644 index 0000000..45126df --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/chdir.rst @@ -0,0 +1,51 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: CHDIR, system, working directory + +.. _chdir: + +CHDIR --- Change working directory +********************************** + +.. function:: CHDIR(NAME) + + Change current working directory to a specified path. + + :param NAME: + The type shall be ``CHARACTER`` of default + kind and shall specify a valid path within the file system. + + :param STATUS: + (Optional) ``INTEGER`` status flag of the default + kind. Returns 0 on success, and a system specific and nonzero error code + otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL CHDIR(NAME [, STATUS]) + STATUS = CHDIR(NAME) + + Example: + .. code-block:: fortran + + PROGRAM test_chdir + CHARACTER(len=255) :: path + CALL getcwd(path) + WRITE(*,*) TRIM(path) + CALL chdir("/tmp") + CALL getcwd(path) + WRITE(*,*) TRIM(path) + END PROGRAM + + See also: + :ref:`GETCWD`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/chmod.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/chmod.rst new file mode 100644 index 0000000..890b4ff --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/chmod.rst @@ -0,0 +1,70 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _chmod: + +CHMOD --- Change access permissions of files +******************************************** + +.. index:: CHMOD(NAME, MODE, STATUS), file system, change access mode + +.. function:: CHMOD(NAME, MODE, STATUS) + + ``CHMOD`` changes the permissions of a file. + + :param NAME: + Scalar ``CHARACTER`` of default kind with the + file name. Trailing blanks are ignored unless the character + ``achar(0)`` is present, then all characters up to and excluding + ``achar(0)`` are used as the file name. + + :param MODE: + Scalar ``CHARACTER`` of default kind giving the + file permission. :samp:`{MODE}` uses the same syntax as the ``chmod`` utility + as defined by the POSIX standard. The argument shall either be a string of + a nonnegative octal number or a symbolic mode. + + :param STATUS: + (optional) scalar ``INTEGER``, which is + ``0`` on success and nonzero otherwise. + + :return: + In either syntax, :samp:`{STATUS}` is set to ``0`` on success and nonzero + otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL CHMOD(NAME, MODE[, STATUS]) + STATUS = CHMOD(NAME, MODE) + + Example: + ``CHMOD`` as subroutine + + .. code-block:: fortran + + program chmod_test + implicit none + integer :: status + call chmod('test.dat','u+x',status) + print *, 'Status: ', status + end program chmod_test + + ``CHMOD`` as function: + + .. code-block:: fortran + + program chmod_test + implicit none + integer :: status + status = chmod('test.dat','u+x') + print *, 'Status: ', status + end program chmod_test
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cloc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cloc.rst new file mode 100644 index 0000000..8261e4d --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cloc.rst @@ -0,0 +1,51 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: C_LOC, procedure pointer, convert C to Fortran + +.. _c_loc: + +C_LOC --- Obtain the C address of an object +******************************************* + +.. function:: C_LOC(X) + + ``C_LOC(X)`` determines the C address of the argument. + + :param X: + 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. + + :return: + The return value is of type ``C_PTR`` and contains the C address + of the argument. + + Standard: + Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = C_LOC(X) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`C_ASSOCIATED`, + :ref:`C_FUNLOC`, + :ref:`C_F_POINTER`, + :ref:`C_F_PROCPOINTER`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cmplx.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cmplx.rst new file mode 100644 index 0000000..790c9d0 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cmplx.rst @@ -0,0 +1,61 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _cmplx: + +CMPLX --- Complex conversion function +************************************* + +.. index:: CMPLX, complex numbers, conversion to, conversion, to complex + +.. function:: CMPLX(X, Y, KIND) + + ``CMPLX(X [, Y [, KIND]])`` returns a complex number where :samp:`{X}` is converted to + the real component. If :samp:`{Y}` is present it is converted to the imaginary + component. If :samp:`{Y}` is not present then the imaginary component is set to + 0.0. If :samp:`{X}` is complex then :samp:`{Y}` must not be present. + + :param X: + The type may be ``INTEGER``, ``REAL``, + or ``COMPLEX``. + + :param Y: + (Optional; only allowed if :samp:`{X}` is not + ``COMPLEX``.) May be ``INTEGER`` or ``REAL``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of ``COMPLEX`` type, with a kind equal to + :samp:`{KIND}` if it is specified. If :samp:`{KIND}` is not specified, the + result is of the default ``COMPLEX`` kind, regardless of the kinds of + :samp:`{X}` and :samp:`{Y}`. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = CMPLX(X [, Y [, KIND]]) + + Example: + .. code-block:: fortran + + program test_cmplx + integer :: i = 42 + real :: x = 3.14 + complex :: z + z = cmplx(i, x) + print *, z, cmplx(x) + end program test_cmplx + + See also: + :ref:`COMPLEX`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cobroadcast.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cobroadcast.rst new file mode 100644 index 0000000..65a2e1e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cobroadcast.rst @@ -0,0 +1,65 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _co_broadcast: + +CO_BROADCAST --- Copy a value to all images the current set of images +********************************************************************* + +.. index:: CO_BROADCAST, Collectives, value broadcasting + +.. function:: CO_BROADCAST(A, SOURCE_IMAGE, STAT, ERRMSG) + + ``CO_BROADCAST`` copies the value of argument :samp:`{A}` on the image with + image index ``SOURCE_IMAGE`` to all images in the current team. :samp:`{A}` + becomes defined as if by intrinsic assignment. If the execution was + successful and :samp:`{STAT}` is present, it is assigned the value zero. If the + execution failed, :samp:`{STAT}` gets assigned a nonzero value and, if present, + :samp:`{ERRMSG}` gets assigned a value describing the occurred error. + + :param A: + 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. + + :param SOURCE_IMAGE: + a scalar integer expression. + It shall have the same value on all images and refer to an + image of the current team. + + :param STAT: + (optional) a scalar integer variable + + :param ERRMSG: + (optional) a scalar character variable + + Standard: + Technical Specification (TS) 18508 or later + + Class: + Collective subroutine + + Syntax: + .. code-block:: fortran + + CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`CO_MAX`, + :ref:`CO_MIN`, + :ref:`CO_SUM`, + :ref:`CO_REDUCE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/comax.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/comax.rst new file mode 100644 index 0000000..d8f1be6 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/comax.rst @@ -0,0 +1,66 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _co_max: + +CO_MAX --- Maximal value on the current set of images +***************************************************** + +.. index:: CO_MAX, Collectives, maximal value + +.. function:: CO_MAX(A, RESULT_IMAGE, STAT, ERRMSG) + + ``CO_MAX`` determines element-wise the maximal value of :samp:`{A}` on all + images of the current team. If :samp:`{RESULT_IMAGE}` is present, the maximum + values are returned in :samp:`{A}` on the specified image only and the value + of :samp:`{A}` on the other images become undefined. If :samp:`{RESULT_IMAGE}` is + not present, the value is returned on all images. If the execution was + successful and :samp:`{STAT}` is present, it is assigned the value zero. If the + execution failed, :samp:`{STAT}` gets assigned a nonzero value and, if present, + :samp:`{ERRMSG}` gets assigned a value describing the occurred error. + + :param A: + shall be an integer, real or character variable, + which has the same type and type parameters on all images of the team. + + :param RESULT_IMAGE: + (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. + + :param STAT: + (optional) a scalar integer variable + + :param ERRMSG: + (optional) a scalar character variable + + Standard: + Technical Specification (TS) 18508 or later + + Class: + Collective subroutine + + Syntax: + .. code-block:: fortran + + CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`CO_MIN`, + :ref:`CO_SUM`, + :ref:`CO_REDUCE`, + :ref:`CO_BROADCAST`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/comin.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/comin.rst new file mode 100644 index 0000000..4bf2739 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/comin.rst @@ -0,0 +1,66 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _co_min: + +CO_MIN --- Minimal value on the current set of images +***************************************************** + +.. index:: CO_MIN, Collectives, minimal value + +.. function:: CO_MIN(A, RESULT_IMAGE, STAT, ERRMSG) + + ``CO_MIN`` determines element-wise the minimal value of :samp:`{A}` on all + images of the current team. If :samp:`{RESULT_IMAGE}` is present, the minimal + values are returned in :samp:`{A}` on the specified image only and the value + of :samp:`{A}` on the other images become undefined. If :samp:`{RESULT_IMAGE}` is + not present, the value is returned on all images. If the execution was + successful and :samp:`{STAT}` is present, it is assigned the value zero. If the + execution failed, :samp:`{STAT}` gets assigned a nonzero value and, if present, + :samp:`{ERRMSG}` gets assigned a value describing the occurred error. + + :param A: + shall be an integer, real or character variable, + which has the same type and type parameters on all images of the team. + + :param RESULT_IMAGE: + (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. + + :param STAT: + (optional) a scalar integer variable + + :param ERRMSG: + (optional) a scalar character variable + + Standard: + Technical Specification (TS) 18508 or later + + Class: + Collective subroutine + + Syntax: + .. code-block:: fortran + + CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`CO_MAX`, + :ref:`CO_SUM`, + :ref:`CO_REDUCE`, + :ref:`CO_BROADCAST`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/commandargumentcount.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/commandargumentcount.rst new file mode 100644 index 0000000..2d344b7 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/commandargumentcount.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _command_argument_count: + +COMMAND_ARGUMENT_COUNT --- Get number of command line arguments +*************************************************************** + +.. index:: COMMAND_ARGUMENT_COUNT, command-line arguments, command-line arguments, number of, arguments, to program + +.. function:: COMMAND_ARGUMENT_COUNT() + + ``COMMAND_ARGUMENT_COUNT`` returns the number of arguments passed on the + command line when the containing program was invoked. + + :return: + The return value is an ``INTEGER`` of default kind. + + Standard: + Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = COMMAND_ARGUMENT_COUNT() + + Example: + .. code-block:: fortran + + program test_command_argument_count + integer :: count + count = command_argument_count() + print *, count + end program test_command_argument_count + + See also: + :ref:`GET_COMMAND`, + :ref:`GET_COMMAND_ARGUMENT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/compileroptions.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/compileroptions.rst new file mode 100644 index 0000000..81552e1 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/compileroptions.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _compiler_options: + +COMPILER_OPTIONS --- Options passed to the compiler +*************************************************** + +.. index:: COMPILER_OPTIONS, flags inquiry function, options inquiry function, compiler flags inquiry function + +.. function:: COMPILER_OPTIONS() + + ``COMPILER_OPTIONS`` returns a string with the options used for + compiling. + + :return: + 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 ``COMPILER_OPTIONS`` intrinsic. + + Standard: + Fortran 2008 + + Class: + Inquiry function of the module ``ISO_FORTRAN_ENV`` + + Syntax: + .. code-block:: fortran + + STR = COMPILER_OPTIONS() + + Arguments: + None + + Example: + .. code-block:: fortran + + use iso_fortran_env + print '(4a)', 'This file was compiled by ', & + compiler_version(), ' using the options ', & + compiler_options() + end + + See also: + :ref:`COMPILER_VERSION`, + :ref:`ISO_FORTRAN_ENV`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/compilerversion.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/compilerversion.rst new file mode 100644 index 0000000..526d272 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/compilerversion.rst @@ -0,0 +1,47 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _compiler_version: + +COMPILER_VERSION --- Compiler version string +******************************************** + +.. index:: COMPILER_VERSION, compiler, name and version, version of the compiler + +.. function:: COMPILER_VERSION() + + ``COMPILER_VERSION`` returns a string with the name and the + version of the compiler. + + :return: + The return value is a default-kind string with system-dependent length. + It contains the name of the compiler and its version number. + + Standard: + Fortran 2008 + + Class: + Inquiry function of the module ``ISO_FORTRAN_ENV`` + + Syntax: + .. code-block:: fortran + + STR = COMPILER_VERSION() + + Arguments: + None + + Example: + .. code-block:: fortran + + use iso_fortran_env + print '(4a)', 'This file was compiled by ', & + compiler_version(), ' using the options ', & + compiler_options() + end + + See also: + :ref:`COMPILER_OPTIONS`, + :ref:`ISO_FORTRAN_ENV`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/complex.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/complex.rst new file mode 100644 index 0000000..dc5d547 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/complex.rst @@ -0,0 +1,50 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: COMPLEX, complex numbers, conversion to, conversion, to complex + +.. _complex: + +COMPLEX --- Complex conversion function +*************************************** + +.. function:: COMPLEX(X, Y) + + ``COMPLEX(X, Y)`` returns a complex number where :samp:`{X}` is converted + to the real component and :samp:`{Y}` is converted to the imaginary + component. + + :param X: + The type may be ``INTEGER`` or ``REAL``. + + :param Y: + The type may be ``INTEGER`` or ``REAL``. + + :return: + If :samp:`{X}` and :samp:`{Y}` are both of ``INTEGER`` type, then the return + value is of default ``COMPLEX`` type. + + Standard: + GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = COMPLEX(X, Y) + + Example: + .. code-block:: fortran + + program test_complex + integer :: i = 42 + real :: x = 3.14 + print *, complex(i, x) + end program test_complex + + See also: + :ref:`CMPLX`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/conjg.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/conjg.rst new file mode 100644 index 0000000..80d3f7b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/conjg.rst @@ -0,0 +1,63 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _conjg: + +.. index:: CONJG + +.. index:: DCONJG + +.. index:: complex conjugate + +CONJG --- Complex conjugate function +************************************ + +.. function:: CONJG(Z) + + ``CONJG(Z)`` returns the conjugate of :samp:`{Z}`. If :samp:`{Z}` is ``(x, y)`` + then the result is ``(x, -y)`` + + :param Z: + The type shall be ``COMPLEX``. + + :return: + The return value is of type ``COMPLEX``. + + Standard: + Fortran 77 and later, has an overload that is a GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + Z = CONJG(Z) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DCONJG(Z)`` + - ``COMPLEX(8) Z`` + - ``COMPLEX(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/coreduce.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/coreduce.rst new file mode 100644 index 0000000..cba765f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/coreduce.rst @@ -0,0 +1,94 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _co_reduce: + +CO_REDUCE --- Reduction of values on the current set of images +************************************************************** + +.. index:: CO_REDUCE, Collectives, generic reduction + +.. function:: CO_REDUCE(A, OPERATOR, RESULT_IMAGE, STAT, ERRMSG) + + ``CO_REDUCE`` determines element-wise the reduction of the value of :samp:`{A}` + on all images of the current team. The pure function passed as :samp:`{OPERATION}` + is used to pairwise reduce the values of :samp:`{A}` by passing either the value + of :samp:`{A}` of different images or the result values of such a reduction as + argument. If :samp:`{A}` is an array, the deduction is done element wise. If + :samp:`{RESULT_IMAGE}` is present, the result values are returned in :samp:`{A}` on + the specified image only and the value of :samp:`{A}` on the other images become + undefined. If :samp:`{RESULT_IMAGE}` is not present, the value is returned on all + images. If the execution was successful and :samp:`{STAT}` is present, it is + assigned the value zero. If the execution failed, :samp:`{STAT}` gets assigned + a nonzero value and, if present, :samp:`{ERRMSG}` gets assigned a value describing + the occurred error. + + :param A: + is an ``INTENT(INOUT)`` argument and shall be + nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer, + it shall be associated. :samp:`{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. + + :param OPERATION: + pure function with two scalar nonallocatable + arguments, which shall be nonpolymorphic and have the same type and type + parameters as :samp:`{A}`. The function shall return a nonallocatable scalar of + the same type and type parameters as :samp:`{A}`. The function shall be the same on + all images and with regards to the arguments mathematically commutative and + associative. Note that :samp:`{OPERATION}` may not be an elemental function, unless + it is an intrisic function. + + :param RESULT_IMAGE: + (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. + + :param STAT: + (optional) a scalar integer variable + + :param ERRMSG: + (optional) a scalar character variable + + Standard: + Technical Specification (TS) 18508 or later + + Class: + Collective subroutine + + Syntax: + .. code-block:: fortran + + CALL CO_REDUCE(A, OPERATION, [, RESULT_IMAGE, STAT, ERRMSG]) + + Example: + .. code-block:: fortran + + 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 + + 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. + + See also: + :ref:`CO_MIN`, + :ref:`CO_MAX`, + :ref:`CO_SUM`, + :ref:`CO_BROADCAST`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cos.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cos.rst new file mode 100644 index 0000000..de283c4 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cos.rst @@ -0,0 +1,91 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _cos: + +.. index:: COS + +.. index:: DCOS + +.. index:: CCOS + +.. index:: ZCOS + +.. index:: CDCOS + +.. index:: trigonometric function, cosine + +.. index:: cosine + +COS --- Cosine function +*********************** + +.. function:: COS(X) + + ``COS(X)`` computes the cosine of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or + ``COMPLEX``. + + :return: + The return value is of the same type and kind as :samp:`{X}`. The real part + of the result is in radians. If :samp:`{X}` is of the type ``REAL``, + the return value lies in the range -1 \leq \cos (x) \leq 1. + + Standard: + Fortran 77 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = COS(X) + + Example: + .. code-block:: fortran + + program test_cos + real :: x = 0.0 + x = cos(x) + end program test_cos + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``COS(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DCOS(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later + * - ``CCOS(X)`` + - ``COMPLEX(4) X`` + - ``COMPLEX(4)`` + - Fortran 77 and later + * - ``ZCOS(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + * - ``CDCOS(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + + See also: + Inverse function: + :ref:`ACOS` + Degrees function: + :ref:`COSD`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cosd.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cosd.rst new file mode 100644 index 0000000..fa54ab4 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cosd.rst @@ -0,0 +1,91 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _cosd: + +.. index:: COSD + +.. index:: DCOSD + +.. index:: CCOSD + +.. index:: ZCOSD + +.. index:: CDCOSD + +.. index:: trigonometric function, cosine, degrees + +.. index:: cosine, degrees + +COSD --- Cosine function, degrees +********************************* + +.. function:: COSD(X) + + ``COSD(X)`` computes the cosine of :samp:`{X}` in degrees. + + :param X: + The type shall be ``REAL`` or + ``COMPLEX``. + + :return: + The return value is of the same type and kind as :samp:`{X}`. The real part + of the result is in degrees. If :samp:`{X}` is of the type ``REAL``, + the return value lies in the range -1 \leq \cosd (x) \leq 1. + + Standard: + GNU extension, enabled with :option:`-fdec-math`. + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = COSD(X) + + Example: + .. code-block:: fortran + + program test_cosd + real :: x = 0.0 + x = cosd(x) + end program test_cosd + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``COSD(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - GNU extension + * - ``DCOSD(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + * - ``CCOSD(X)`` + - ``COMPLEX(4) X`` + - ``COMPLEX(4)`` + - GNU extension + * - ``ZCOSD(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + * - ``CDCOSD(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + + See also: + Inverse function: + :ref:`ACOSD` + Radians function: + :ref:`COS`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cosh.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cosh.rst new file mode 100644 index 0000000..cf421dd --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cosh.rst @@ -0,0 +1,73 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _cosh: + +.. index:: COSH + +.. index:: DCOSH + +.. index:: hyperbolic cosine + +.. index:: hyperbolic function, cosine + +.. index:: cosine, hyperbolic + +COSH --- Hyperbolic cosine function +*********************************** + +.. function:: COSH(X) + + ``COSH(X)`` computes the hyperbolic cosine of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`. If :samp:`{X}` is + complex, the imaginary part of the result is in radians. If :samp:`{X}` + is ``REAL``, the return value has a lower bound of one, + \cosh (x) \geq 1. + + Standard: + Fortran 77 and later, for a complex argument Fortran 2008 or later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + X = COSH(X) + + Example: + .. code-block:: fortran + + program test_cosh + real(8) :: x = 1.0_8 + x = cosh(x) + end program test_cosh + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``COSH(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DCOSH(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later + + See also: + Inverse function: + :ref:`ACOSH`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cosum.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cosum.rst new file mode 100644 index 0000000..49d4cbd --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cosum.rst @@ -0,0 +1,67 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _co_sum: + +CO_SUM --- Sum of values on the current set of images +***************************************************** + +.. index:: CO_SUM, Collectives, sum of values + +.. function:: CO_SUM(A, RESULT_IMAGE, STAT, ERRMSG) + + ``CO_SUM`` sums up the values of each element of :samp:`{A}` on all + images of the current team. If :samp:`{RESULT_IMAGE}` is present, the summed-up + values are returned in :samp:`{A}` on the specified image only and the value + of :samp:`{A}` on the other images become undefined. If :samp:`{RESULT_IMAGE}` is + not present, the value is returned on all images. If the execution was + successful and :samp:`{STAT}` is present, it is assigned the value zero. If the + execution failed, :samp:`{STAT}` gets assigned a nonzero value and, if present, + :samp:`{ERRMSG}` gets assigned a value describing the occurred error. + + :param A: + shall be an integer, real or complex variable, + which has the same type and type parameters on all images of the team. + + :param RESULT_IMAGE: + (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. + + :param STAT: + (optional) a scalar integer variable + + :param ERRMSG: + (optional) a scalar character variable + + Standard: + Technical Specification (TS) 18508 or later + + Class: + Collective subroutine + + Syntax: + .. code-block:: fortran + + CALL CO_SUM(A [, RESULT_IMAGE, STAT, ERRMSG]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`CO_MAX`, + :ref:`CO_MIN`, + :ref:`CO_REDUCE`, + :ref:`CO_BROADCAST`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cotan.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cotan.rst new file mode 100644 index 0000000..82abca8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cotan.rst @@ -0,0 +1,71 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _cotan: + +.. index:: COTAN + +.. index:: DCOTAN + +.. index:: trigonometric function, cotangent + +.. index:: cotangent + +COTAN --- Cotangent function +**************************** + +.. function:: COTAN(X) + + ``COTAN(X)`` computes the cotangent of :samp:`{X}`. Equivalent to ``COS(x)`` + divided by ``SIN(x)``, or ``1 / TAN(x)``. + + :param X: + The type shall be ``REAL`` or ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`, and its value is in radians. + + Standard: + GNU extension, enabled with :option:`-fdec-math`. + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = COTAN(X) + + Example: + .. code-block:: fortran + + program test_cotan + real(8) :: x = 0.165_8 + x = cotan(x) + end program test_cotan + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``COTAN(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - GNU extension + * - ``DCOTAN(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + + See also: + Converse function: + :ref:`TAN` + Degrees function: + :ref:`COTAND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cotand.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cotand.rst new file mode 100644 index 0000000..e101c52 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cotand.rst @@ -0,0 +1,74 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _cotand: + +.. index:: COTAND + +.. index:: DCOTAND + +.. index:: trigonometric function, cotangent, degrees + +.. index:: cotangent, degrees + +COTAND --- Cotangent function, degrees +************************************** + +.. function:: COTAND(X) + + ``COTAND(X)`` computes the cotangent of :samp:`{X}` in degrees. Equivalent to + ``COSD(x)`` divided by ``SIND(x)``, or ``1 / TAND(x)``. + + :param X: + The type shall be ``REAL`` or ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`, and its value is in degrees. + + 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. + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = COTAND(X) + + Example: + .. code-block:: fortran + + program test_cotand + real(8) :: x = 0.165_8 + x = cotand(x) + end program test_cotand + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``COTAND(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - GNU extension + * - ``DCOTAND(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + + See also: + Converse function: + :ref:`TAND` + Radians function: + :ref:`COTAN`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/count.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/count.rst new file mode 100644 index 0000000..e0988f7 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/count.rst @@ -0,0 +1,72 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: COUNT, array, conditionally count elements, array, element counting, array, number of elements + +.. _count: + +COUNT --- Count function +************************ + +.. function:: COUNT(MASK , DIM, KIND) + + Counts the number of ``.TRUE.`` elements in a logical :samp:`{MASK}`, + or, if the :samp:`{DIM}` argument is supplied, counts the number of + elements along each row of the array in the :samp:`{DIM}` direction. + If the array has zero size, or all of the elements of :samp:`{MASK}` are + ``.FALSE.``, then the result is ``0``. + + :param MASK: + The type shall be ``LOGICAL``. + + :param DIM: + (Optional) The type shall be ``INTEGER``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + If :samp:`{DIM}` is present, the result is an array with a rank one less + than the rank of :samp:`{ARRAY}`, and a size corresponding to the shape + of :samp:`{ARRAY}` with the :samp:`{DIM}` dimension removed. + + Standard: + Fortran 90 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = COUNT(MASK [, DIM, KIND]) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cputime.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cputime.rst new file mode 100644 index 0000000..c10df47 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cputime.rst @@ -0,0 +1,49 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: CPU_TIME, time, elapsed + +.. _cpu_time: + +CPU_TIME --- CPU elapsed time in seconds +**************************************** + +.. function:: CPU_TIME(TIME) + + Returns a ``REAL`` value representing the elapsed CPU time in + seconds. This is useful for testing segments of code to determine + execution time. + + :param TIME: + The type shall be ``REAL`` with ``INTENT(OUT)``. + + :return: + None + + Standard: + Fortran 95 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL CPU_TIME(TIME) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`SYSTEM_CLOCK`, + :ref:`DATE_AND_TIME`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/cshift.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/cshift.rst new file mode 100644 index 0000000..bc22279 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/cshift.rst @@ -0,0 +1,61 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _cshift: + +CSHIFT --- Circular shift elements of an array +********************************************** + +.. index:: CSHIFT, array, shift circularly, array, permutation, array, rotate + +.. function:: CSHIFT(ARRAY, SHIFT, DIM) + + ``CSHIFT(ARRAY, SHIFT [, DIM])`` performs a circular shift on elements of + :samp:`{ARRAY}` along the dimension of :samp:`{DIM}`. If :samp:`{DIM}` is omitted it is + taken to be ``1``. :samp:`{DIM}` is a scalar of type ``INTEGER`` in the + range of 1 \leq DIM \leq n) where n is the rank of :samp:`{ARRAY}`. + If the rank of :samp:`{ARRAY}` is one, then all elements of :samp:`{ARRAY}` are shifted + by :samp:`{SHIFT}` places. If rank is greater than one, then all complete rank one + sections of :samp:`{ARRAY}` along the given dimension are shifted. Elements + shifted out one end of each rank one section are shifted back in the other end. + + :param ARRAY: + Shall be an array of any type. + + :param SHIFT: + The type shall be ``INTEGER``. + + :param DIM: + The type shall be ``INTEGER``. + + :return: + Returns an array of same type and rank as the :samp:`{ARRAY}` argument. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = CSHIFT(ARRAY, SHIFT [, DIM]) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/csizeof.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/csizeof.rst new file mode 100644 index 0000000..2cae1e8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/csizeof.rst @@ -0,0 +1,55 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: C_SIZEOF, expression size, size of an expression + +.. _c_sizeof: + +C_SIZEOF --- Size in bytes of an expression +******************************************* + +.. function:: C_SIZEOF(X) + + ``C_SIZEOF(X)`` calculates the number of bytes of storage the + expression ``X`` occupies. + + :param X: + The argument shall be an interoperable data entity. + + :return: + The return value is of type integer and of the system-dependent kind + ``C_SIZE_T`` (from the ``ISO_C_BINDING`` module). Its value is the + number of bytes occupied by the argument. If the argument has the + ``POINTER`` attribute, the number of bytes of the storage area pointed + to is returned. If the argument is of a derived type with ``POINTER`` + or ``ALLOCATABLE`` components, the return value does not account for + the sizes of the data pointed to by these components. + + Standard: + Fortran 2008 + + Class: + Inquiry function of the module ``ISO_C_BINDING`` + + Syntax: + .. code-block:: fortran + + N = C_SIZEOF(X) + + Example: + .. code-block:: fortran + + use iso_c_binding + integer(c_int) :: i + real(c_float) :: r, s(5) + print *, (c_sizeof(s)/c_sizeof(r) == 5) + end + + The example will print ``T`` unless you are using a platform + where default ``REAL`` variables are unusually padded. + + See also: + :ref:`SIZEOF`, + :ref:`STORAGE_SIZE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ctime.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ctime.rst new file mode 100644 index 0000000..1cfc97a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ctime.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ctime: + +CTIME --- Convert a time into a string +************************************** + +.. index:: CTIME, time, conversion to string, conversion, to string + +.. function:: CTIME(TIME, RESULT) + + ``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`. + + :param TIME: + The type shall be of type ``INTEGER``. + + :param RESULT: + The type shall be of type ``CHARACTER`` and + of default kind. It is an ``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. + + :return: + The converted date and time as a string. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL CTIME(TIME, RESULT). + RESULT = CTIME(TIME). + + Example: + .. code-block:: fortran + + 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 + + See Also: + :ref:`DATE_AND_TIME`, + :ref:`GMTIME`, + :ref:`LTIME`, + :ref:`TIME`, + :ref:`TIME8`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/dateandtime.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/dateandtime.rst new file mode 100644 index 0000000..42268b8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/dateandtime.rst @@ -0,0 +1,70 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: DATE_AND_TIME, date, current, current date, time, current, current time + +.. _date_and_time: + +DATE_AND_TIME --- Date and time subroutine +****************************************** + +.. function:: DATE_AND_TIME(DATE, TIME, ZONE, VALUES) + + ``DATE_AND_TIME(DATE, TIME, ZONE, VALUES)`` gets the corresponding date and + time information from the real-time system clock. :samp:`{DATE}` is + ``INTENT(OUT)`` and has form ccyymmdd. :samp:`{TIME}` is ``INTENT(OUT)`` and + has form hhmmss.sss. :samp:`{ZONE}` is ``INTENT(OUT)`` and has form (+-)hhmm, + representing the difference with respect to Coordinated Universal Time (UTC). + Unavailable time and date parameters return blanks. + + :param DATE: + (Optional) The type shall be ``CHARACTER(LEN=8)`` + or larger, and of default kind. + + :param TIME: + (Optional) The type shall be ``CHARACTER(LEN=10)`` + or larger, and of default kind. + + :param ZONE: + (Optional) The type shall be ``CHARACTER(LEN=5)`` + or larger, and of default kind. + + :param VALUES: + (Optional) The type shall be ``INTEGER(8)``. + + :return: + None + + Standard: + Fortran 90 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`CPU_TIME`, + :ref:`SYSTEM_CLOCK`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/dble.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/dble.rst new file mode 100644 index 0000000..60108a9 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/dble.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: DBLE, conversion, to real + +.. _dble: + +DBLE --- Double conversion function +*********************************** + +.. function:: DBLE(A) + + ``DBLE(A)`` Converts :samp:`{A}` to double precision real type. + + :param A: + The type shall be ``INTEGER``, ``REAL``, + or ``COMPLEX``. + + :return: + The return value is of type double precision real. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = DBLE(A) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`REAL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/dcmplx.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/dcmplx.rst new file mode 100644 index 0000000..358e937 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/dcmplx.rst @@ -0,0 +1,54 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _dcmplx: + +DCMPLX --- Double complex conversion function +********************************************* + +.. index:: DCMPLX, complex numbers, conversion to, conversion, to complex + +.. function:: DCMPLX(X, Y) + + ``DCMPLX(X [,Y])`` returns a double complex number where :samp:`{X}` is + converted to the real component. If :samp:`{Y}` is present it is converted to the + imaginary component. If :samp:`{Y}` is not present then the imaginary component is + set to 0.0. If :samp:`{X}` is complex then :samp:`{Y}` must not be present. + + :param X: + The type may be ``INTEGER``, ``REAL``, + or ``COMPLEX``. + + :param Y: + (Optional if :samp:`{X}` is not ``COMPLEX``.) May be + ``INTEGER`` or ``REAL``. + + :return: + The return value is of type ``COMPLEX(8)`` + + Standard: + GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = DCMPLX(X [, Y]) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/digits.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/digits.rst new file mode 100644 index 0000000..895a32c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/digits.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: DIGITS, model representation, significant digits + +.. _digits: + +DIGITS --- Significant binary digits function +********************************************* + +.. function:: DIGITS(X) + + ``DIGITS(X)`` returns the number of significant binary digits of the internal + model representation of :samp:`{X}`. For example, on a system using a 32-bit + floating point representation, a default real number would likely return 24. + + :param X: + The type may be ``INTEGER`` or ``REAL``. + + :return: + The return value is of type ``INTEGER``. + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = DIGITS(X) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/dim.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/dim.rst new file mode 100644 index 0000000..7a5f2e4 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/dim.rst @@ -0,0 +1,78 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _dim: + +.. index:: DIM + +.. index:: IDIM + +.. index:: DDIM + +.. index:: positive difference + +DIM --- Positive difference +*************************** + +.. function:: DIM(X,Y) + + ``DIM(X,Y)`` returns the difference ``X-Y`` if the result is positive; + otherwise returns zero. + + :param X: + The type shall be ``INTEGER`` or ``REAL`` + + :param Y: + The type shall be the same type and kind as :samp:`{X}`. (As + a GNU extension, arguments of different kinds are permitted.) + + :return: + The return value is of type ``INTEGER`` or ``REAL``. (As a GNU + extension, kind is the largest kind of the actual arguments.) + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = DIM(X, Y) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DIM(X,Y)`` + - ``REAL(4) X, Y`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``IDIM(X,Y)`` + - ``INTEGER(4) X, Y`` + - ``INTEGER(4)`` + - Fortran 77 and later + * - ``DDIM(X,Y)`` + - ``REAL(8) X, Y`` + - ``REAL(8)`` + - Fortran 77 and later
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/dotproduct.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/dotproduct.rst new file mode 100644 index 0000000..396e221 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/dotproduct.rst @@ -0,0 +1,57 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: DOT_PRODUCT, dot product, vector product, product, vector + +.. _dot_product: + +DOT_PRODUCT --- Dot product function +************************************ + +.. function:: DOT_PRODUCT(VECTOR_A, VECTOR_B) + + ``DOT_PRODUCT(VECTOR_A, VECTOR_B)`` computes the dot product multiplication + of two vectors :samp:`{VECTOR_A}` and :samp:`{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 ``INTEGER`` or ``REAL``, the result is + ``SUM(VECTOR_A*VECTOR_B)``. If the vectors are ``COMPLEX``, the result + is ``SUM(CONJG(VECTOR_A)*VECTOR_B)``. If the vectors are ``LOGICAL``, + the result is ``ANY(VECTOR_A .AND. VECTOR_B)``. + + :param VECTOR_A: + The type shall be numeric or ``LOGICAL``, rank 1. + + :param VECTOR_B: + The type shall be numeric if :samp:`{VECTOR_A}` is of numeric type or ``LOGICAL`` if :samp:`{VECTOR_A}` is of type ``LOGICAL``. :samp:`{VECTOR_B}` shall be a rank-one array. + + :return: + If the arguments are numeric, the return value is a scalar of numeric type, + ``INTEGER``, ``REAL``, or ``COMPLEX``. If the arguments are + ``LOGICAL``, the return value is ``.TRUE.`` or ``.FALSE.``. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/dprod.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/dprod.rst new file mode 100644 index 0000000..63dca09 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/dprod.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _dprod: + +.. index:: DPROD + +.. index:: product, double-precision + +DPROD --- Double product function +********************************* + +.. function:: DPROD(X,Y) + + ``DPROD(X,Y)`` returns the product ``X*Y``. + + :param X: + The type shall be ``REAL``. + + :param Y: + The type shall be ``REAL``. + + :return: + The return value is of type ``REAL(8)``. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = DPROD(X, Y) + + Example: + .. code-block:: fortran + + program test_dprod + real :: x = 5.2 + real :: y = 2.3 + real(8) :: d + d = dprod(x,y) + print *, d + end program test_dprod + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DPROD(X,Y)`` + - ``REAL(4) X, Y`` + - ``REAL(8)`` + - Fortran 77 and later
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/dreal.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/dreal.rst new file mode 100644 index 0000000..f84da91 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/dreal.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: DREAL, complex numbers, real part + +.. _dreal: + +DREAL --- Double real part function +*********************************** + +.. function:: DREAL(Z) + + ``DREAL(Z)`` returns the real part of complex variable :samp:`{Z}`. + + :param A: + The type shall be ``COMPLEX(8)``. + + :return: + The return value is of type ``REAL(8)``. + + Standard: + GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = DREAL(A) + + Example: + .. code-block:: fortran + + program test_dreal + complex(8) :: z = (1.3_8,7.2_8) + print *, dreal(z) + end program test_dreal + + See also: + :ref:`AIMAG`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/dshiftl.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/dshiftl.rst new file mode 100644 index 0000000..24ab08e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/dshiftl.rst @@ -0,0 +1,52 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: DSHIFTL, left shift, combined, shift, left + +.. _dshiftl: + +DSHIFTL --- Combined left shift +******************************* + +.. function:: DSHIFTL(I, J, SHIFT) + + ``DSHIFTL(I, J, SHIFT)`` combines bits of :samp:`{I}` and :samp:`{J}`. The + rightmost :samp:`{SHIFT}` bits of the result are the leftmost :samp:`{SHIFT}` + bits of :samp:`{J}`, and the remaining bits are the rightmost bits of + :samp:`{I}`. + + :param I: + Shall be of type ``INTEGER`` or a BOZ constant. + + :param J: + Shall be of type ``INTEGER`` or a BOZ constant. + If both :samp:`{I}` and :samp:`{J}` have integer type, then they shall have + the same kind type parameter. :samp:`{I}` and :samp:`{J}` shall not both be + BOZ constants. + + :param SHIFT: + Shall be of type ``INTEGER``. It shall + be nonnegative. If :samp:`{I}` is not a BOZ constant, then :samp:`{SHIFT}` + shall be less than or equal to ``BIT_SIZE(I)`` ; otherwise, + :samp:`{SHIFT}` shall be less than or equal to ``BIT_SIZE(J)``. + + :return: + If either :samp:`{I}` or :samp:`{J}` is a BOZ constant, it is first converted + as if by the intrinsic function ``INT`` to an integer type with the + kind type parameter of the other. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = DSHIFTL(I, J, SHIFT) + + See also: + :ref:`DSHIFTR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/dshiftr.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/dshiftr.rst new file mode 100644 index 0000000..a4d4ec4 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/dshiftr.rst @@ -0,0 +1,52 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: DSHIFTR, right shift, combined, shift, right + +.. _dshiftr: + +DSHIFTR --- Combined right shift +******************************** + +.. function:: DSHIFTR(I, J, SHIFT) + + ``DSHIFTR(I, J, SHIFT)`` combines bits of :samp:`{I}` and :samp:`{J}`. The + leftmost :samp:`{SHIFT}` bits of the result are the rightmost :samp:`{SHIFT}` + bits of :samp:`{I}`, and the remaining bits are the leftmost bits of + :samp:`{J}`. + + :param I: + Shall be of type ``INTEGER`` or a BOZ constant. + + :param J: + Shall be of type ``INTEGER`` or a BOZ constant. + If both :samp:`{I}` and :samp:`{J}` have integer type, then they shall have + the same kind type parameter. :samp:`{I}` and :samp:`{J}` shall not both be + BOZ constants. + + :param SHIFT: + Shall be of type ``INTEGER``. It shall + be nonnegative. If :samp:`{I}` is not a BOZ constant, then :samp:`{SHIFT}` + shall be less than or equal to ``BIT_SIZE(I)`` ; otherwise, + :samp:`{SHIFT}` shall be less than or equal to ``BIT_SIZE(J)``. + + :return: + If either :samp:`{I}` or :samp:`{J}` is a BOZ constant, it is first converted + as if by the intrinsic function ``INT`` to an integer type with the + kind type parameter of the other. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = DSHIFTR(I, J, SHIFT) + + See also: + :ref:`DSHIFTL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/dtime.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/dtime.rst new file mode 100644 index 0000000..4f63d97 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/dtime.rst @@ -0,0 +1,64 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: DTIME, time, elapsed, elapsed time + +.. _dtime: + +DTIME --- Execution time subroutine (or function) +************************************************* + +.. function:: DTIME(VALUES, TIME) + + ``DTIME(VALUES, TIME)`` initially returns the number of seconds of runtime + since the start of the process's execution in :samp:`{TIME}`. :samp:`{VALUES}` + returns the user and system components of this time in ``VALUES(1)`` and + ``VALUES(2)`` respectively. :samp:`{TIME}` is equal to ``VALUES(1) + + VALUES(2)``. + + :param VALUES: + The type shall be ``REAL(4), DIMENSION(2)``. + + :param TIME: + The type shall be ``REAL(4)``. + + :return: + Elapsed time in seconds since the last invocation or since the start of program + execution if not called before. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL DTIME(VALUES, TIME). + TIME = DTIME(VALUES), (not recommended). + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`CPU_TIME`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/eoshift.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/eoshift.rst new file mode 100644 index 0000000..93f1e5a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/eoshift.rst @@ -0,0 +1,67 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _eoshift: + +EOSHIFT --- End-off shift elements of an array +********************************************** + +.. index:: EOSHIFT, array, shift + +.. function:: EOSHIFT(ARRAY, SHIFT, BOUNDARY, DIM) + + ``EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])`` performs an end-off shift on + elements of :samp:`{ARRAY}` along the dimension of :samp:`{DIM}`. If :samp:`{DIM}` is + omitted it is taken to be ``1``. :samp:`{DIM}` is a scalar of type + ``INTEGER`` in the range of 1 \leq DIM \leq n) where n is the + rank of :samp:`{ARRAY}`. If the rank of :samp:`{ARRAY}` is one, then all elements of + :samp:`{ARRAY}` are shifted by :samp:`{SHIFT}` places. If rank is greater than one, + then all complete rank one sections of :samp:`{ARRAY}` along the given dimension are + shifted. Elements shifted out one end of each rank one section are dropped. If + :samp:`{BOUNDARY}` is present then the corresponding value of from :samp:`{BOUNDARY}` + is copied back in the other end. If :samp:`{BOUNDARY}` is not present then the + following are copied in depending on the type of :samp:`{ARRAY}`. + + :param ARRAY: + May be any type, not scalar. + + :param SHIFT: + The type shall be ``INTEGER``. + + :param BOUNDARY: + Same type as :samp:`{ARRAY}`. + + :param DIM: + The type shall be ``INTEGER``. + + :return: + Returns an array of same type and rank as the :samp:`{ARRAY}` argument. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM]) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/epsilon.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/epsilon.rst new file mode 100644 index 0000000..6ff2f2e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/epsilon.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: EPSILON, model representation, epsilon + +.. _epsilon: + +EPSILON --- Epsilon function +**************************** + +.. function:: EPSILON(X) + + ``EPSILON(X)`` returns the smallest number :samp:`{E}` of the same kind + as :samp:`{X}` such that 1 + E > 1. + + :param X: + The type shall be ``REAL``. + + :return: + The return value is of same type as the argument. + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = EPSILON(X) + + Example: + .. code-block:: fortran + + program test_epsilon + real :: x = 3.143 + real(8) :: y = 2.33 + print *, EPSILON(x) + print *, EPSILON(y) + end program test_epsilon
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/erf.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/erf.rst new file mode 100644 index 0000000..9a1c6de --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/erf.rst @@ -0,0 +1,57 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _erf: + +.. index:: ERF + +.. index:: error function + +ERF --- Error function +*********************** + +.. function:: ERF(X) + + ``ERF(X)`` computes the error function of :samp:`{X}`. + + :param X: + The type shall be ``REAL``. + + :return: + The return value is of type ``REAL``, of the same kind as + :samp:`{X}` and lies in the range -1 \leq erf (x) \leq 1 . + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ERF(X) + + Example: + .. code-block:: fortran + + program test_erf + real(8) :: x = 0.17_8 + x = erf(x) + end program test_erf + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DERF(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/erfc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/erfc.rst new file mode 100644 index 0000000..d6ee377 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/erfc.rst @@ -0,0 +1,57 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _erfc: + +.. index:: ERFC + +.. index:: error function, complementary + +ERFC --- Error function +************************ + +.. function:: ERFC(X) + + ``ERFC(X)`` computes the complementary error function of :samp:`{X}`. + + :param X: + The type shall be ``REAL``. + + :return: + The return value is of type ``REAL`` and of the same kind as :samp:`{X}`. + It lies in the range 0 \leq erfc (x) \leq 2 . + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ERFC(X) + + Example: + .. code-block:: fortran + + program test_erfc + real(8) :: x = 0.17_8 + x = erfc(x) + end program test_erfc + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DERFC(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/erfcscaled.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/erfcscaled.rst new file mode 100644 index 0000000..7842cb5 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/erfcscaled.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ERFC_SCALED, error function, complementary, exponentially-scaled + +.. _erfc_scaled: + +ERFC_SCALED --- Error function +******************************* + +.. function:: ERFC_SCALED(X) + + ``ERFC_SCALED(X)`` computes the exponentially-scaled complementary + error function of :samp:`{X}`. + + :param X: + The type shall be ``REAL``. + + :return: + The return value is of type ``REAL`` and of the same kind as :samp:`{X}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ERFC_SCALED(X) + + Example: + .. code-block:: fortran + + program test_erfc_scaled + real(8) :: x = 0.17_8 + x = erfc_scaled(x) + end program test_erfc_scaled
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/etime.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/etime.rst new file mode 100644 index 0000000..63d7431 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/etime.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ETIME, time, elapsed + +.. _etime: + +ETIME --- Execution time subroutine (or function) +************************************************* + +.. function:: ETIME(VALUES, TIME) + + ``ETIME(VALUES, TIME)`` returns the number of seconds of runtime + since the start of the process's execution in :samp:`{TIME}`. :samp:`{VALUES}` + returns the user and system components of this time in ``VALUES(1)`` and + ``VALUES(2)`` respectively. :samp:`{TIME}` is equal to ``VALUES(1) + VALUES(2)``. + + :param VALUES: + The type shall be ``REAL(4), DIMENSION(2)``. + + :param TIME: + The type shall be ``REAL(4)``. + + :return: + Elapsed time in seconds since the start of program execution. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL ETIME(VALUES, TIME). + TIME = ETIME(VALUES), (not recommended). + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`CPU_TIME`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/eventquery.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/eventquery.rst new file mode 100644 index 0000000..f676ec0 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/eventquery.rst @@ -0,0 +1,57 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _event_query: + +EVENT_QUERY --- Query whether a coarray event has occurred +********************************************************** + +.. index:: EVENT_QUERY, Events, EVENT_QUERY + +.. function:: EVENT_QUERY(EVENT, COUNT, STAT) + + ``EVENT_QUERY`` assignes the number of events to :samp:`{COUNT}` which have been + posted to the :samp:`{EVENT}` variable and not yet been removed by calling + ``EVENT WAIT``. When :samp:`{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 :samp:`{COUNT}` is assigned the value -1. + + :param EVENT: + (intent(IN)) Scalar of type ``EVENT_TYPE``, + defined in ``ISO_FORTRAN_ENV`` ; shall not be coindexed. + + :param COUNT: + (intent(out))Scalar integer with at least the + precision of default integer. + + :param STAT: + (optional) Scalar default-kind integer variable. + + Standard: + TS 18508 or later + + Class: + subroutine + + Syntax: + .. code-block:: fortran + + CALL EVENT_QUERY (EVENT, COUNT [, STAT]) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/executecommandline.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/executecommandline.rst new file mode 100644 index 0000000..cfb3dff --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/executecommandline.rst @@ -0,0 +1,70 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _execute_command_line: + +EXECUTE_COMMAND_LINE --- Execute a shell command +************************************************ + +.. index:: EXECUTE_COMMAND_LINE, system, system call, command line + +.. function:: EXECUTE_COMMAND_LINE(COMMAND, WAIT, EXITSTAT, CMDSTAT, CMDMSG) + + ``EXECUTE_COMMAND_LINE`` runs a shell command, synchronously or + asynchronously. + + :param COMMAND: + Shall be a default ``CHARACTER`` scalar. + + :param WAIT: + (Optional) Shall be a default ``LOGICAL`` scalar. + + :param EXITSTAT: + (Optional) Shall be an ``INTEGER`` of the + default kind. + + :param CMDSTAT: + (Optional) Shall be an ``INTEGER`` of the + default kind. + + :param CMDMSG: + (Optional) Shall be an ``CHARACTER`` scalar of the + default kind. + + Standard: + Fortran 2008 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ]) + + Example: + .. code-block:: fortran + + 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 + + Note: + Because this intrinsic is implemented in terms of the ``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. + + See also: + :ref:`SYSTEM`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/exit.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/exit.rst new file mode 100644 index 0000000..40ac4bd --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/exit.rst @@ -0,0 +1,47 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _exit: + +EXIT --- Exit the program with status. +*************************************** + +.. index:: EXIT, program termination, terminate program + +.. function:: EXIT(STATUS) + + ``EXIT`` causes immediate termination of the program with status. If status + is omitted it returns the canonical *success* for the system. All Fortran + I/O units are closed. + + :param STATUS: + Shall be an ``INTEGER`` of the default kind. + + :return: + ``STATUS`` is passed to the parent process on exit. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL EXIT([STATUS]) + + Example: + .. code-block:: fortran + + program test_exit + integer :: STATUS = 0 + print *, 'This program is going to exit.' + call EXIT(STATUS) + end program test_exit + + See also: + :ref:`ABORT`, + :ref:`KILL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/exp.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/exp.rst new file mode 100644 index 0000000..205ad27 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/exp.rst @@ -0,0 +1,83 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _exp: + +.. index:: EXP + +.. index:: DEXP + +.. index:: CEXP + +.. index:: ZEXP + +.. index:: CDEXP + +.. index:: exponential function + +.. index:: logarithm function, inverse + +EXP --- Exponential function +***************************** + +.. function:: EXP(X) + + ``EXP(X)`` computes the base e exponential of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or + ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`. + + Standard: + Fortran 77 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = EXP(X) + + Example: + .. code-block:: fortran + + program test_exp + real :: x = 1.0 + x = exp(x) + end program test_exp + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``EXP(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DEXP(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later + * - ``CEXP(X)`` + - ``COMPLEX(4) X`` + - ``COMPLEX(4)`` + - Fortran 77 and later + * - ``ZEXP(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + * - ``CDEXP(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/exponent.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/exponent.rst new file mode 100644 index 0000000..83c7aa0 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/exponent.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: EXPONENT, real number, exponent, floating point, exponent + +.. _exponent: + +EXPONENT --- Exponent function +******************************* + +.. function:: EXPONENT(X) + + ``EXPONENT(X)`` returns the value of the exponent part of :samp:`{X}`. If :samp:`{X}` + is zero the value returned is zero. + + :param X: + The type shall be ``REAL``. + + :return: + The return value is of type default ``INTEGER``. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = EXPONENT(X) + + Example: + .. code-block:: fortran + + program test_exponent + real :: x = 1.0 + integer :: i + i = exponent(x) + print *, i + print *, exponent(0.0) + end program test_exponent
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/extendstypeof.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/extendstypeof.rst new file mode 100644 index 0000000..1df242e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/extendstypeof.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: EXTENDS_TYPE_OF + +.. _extends_type_of: + +EXTENDS_TYPE_OF --- Query dynamic type for extension +***************************************************** + +.. function:: EXTENDS_TYPE_OF(A, MOLD) + + Query dynamic type for extension. + + :param A: + Shall be an object of extensible declared type or + unlimited polymorphic. + + :param MOLD: + Shall be an object of extensible declared type or + unlimited polymorphic. + + :return: + 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. + + Standard: + Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = EXTENDS_TYPE_OF(A, MOLD) + + See also: + :ref:`SAME_TYPE_AS`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/fdate.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/fdate.rst new file mode 100644 index 0000000..1b780a5 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/fdate.rst @@ -0,0 +1,57 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FDATE, time, current, current time, date, current, current date + +.. _fdate: + +FDATE --- Get the current time as a string +****************************************** + +.. function:: FDATE(DATE) + + ``FDATE(DATE)`` returns the current date (using the same format as + :ref:`CTIME`) in :samp:`{DATE}`. It is equivalent to ``CALL CTIME(DATE, + TIME())``. + + :param DATE: + The type shall be of type ``CHARACTER`` of the + default kind. It is an ``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. + + :return: + The current date and time as a string. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL FDATE(DATE). + DATE = FDATE(). + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`DATE_AND_TIME`, + :ref:`CTIME`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/fget.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/fget.rst new file mode 100644 index 0000000..e9ac9eb --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/fget.rst @@ -0,0 +1,60 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FGET, read character, stream mode, stream mode, read character, file operation, read character + +.. _fget: + +FGET --- Read a single character in stream mode from stdin +*********************************************************** + +.. function:: FGET(C) + + 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. + + :param C: + The type shall be ``CHARACTER`` and of default + kind. + + :param STATUS: + (Optional) status flag of type ``INTEGER``. + Returns 0 on success, -1 on end-of-file, and a system specific positive + error code otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL FGET(C [, STATUS]) + STATUS = FGET(C) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`FGETC`, + :ref:`FPUT`, + :ref:`FPUTC`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/fgetc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/fgetc.rst new file mode 100644 index 0000000..7677fdc --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/fgetc.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FGETC, read character, stream mode, stream mode, read character, file operation, read character + +.. _fgetc: + +FGETC --- Read a single character in stream mode +************************************************ + +.. function:: FGETC(UNIT, C) + + 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. + + :param UNIT: + The type shall be ``INTEGER``. + + :param C: + The type shall be ``CHARACTER`` and of default + kind. + + :param STATUS: + (Optional) status flag of type ``INTEGER``. + Returns 0 on success, -1 on end-of-file and a system specific positive + error code otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL FGETC(UNIT, C [, STATUS]) + STATUS = FGETC(UNIT, C) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`FGET`, + :ref:`FPUT`, + :ref:`FPUTC`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/findloc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/findloc.rst new file mode 100644 index 0000000..7361872 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/findloc.rst @@ -0,0 +1,78 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _findloc: + +FINDLOC --- Search an array for a value +*************************************** + +.. index:: FINDLOC, findloc + +.. function:: FINDLOC(ARRAY, VALUE, MASK, KIND, BACK) + + Determines the location of the element in the array with the value + given in the :samp:`{VALUE}` argument, or, if the :samp:`{DIM}` argument is + supplied, determines the locations of the elements equal to the + :samp:`{VALUE}` argument element along each + row of the array in the :samp:`{DIM}` direction. If :samp:`{MASK}` is + present, only the elements for which :samp:`{MASK}` is ``.TRUE.`` are + considered. If more than one element in the array has the value + :samp:`{VALUE}`, the location returned is that of the first such element + in array element order if the :samp:`{BACK}` is not present or if it is + ``.FALSE.``. If :samp:`{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 :samp:`{MASK}` are ``.FALSE.``, then the result is an array + of zeroes. Similarly, if :samp:`{DIM}` is supplied and all of the + elements of :samp:`{MASK}` along a given row are zero, the result value + for that row is zero. + + :param ARRAY: + Shall be an array of intrinsic type. + + :param VALUE: + A scalar of intrinsic type which is in type + conformance with :samp:`{ARRAY}`. + + :param DIM: + (Optional) Shall be a scalar of type + ``INTEGER``, with a value between one and the rank of :samp:`{ARRAY}`, + inclusive. It may not be an optional dummy argument. + + :param MASK: + (Optional) Shall be of type ``LOGICAL``, + and conformable with :samp:`{ARRAY}`. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :param BACK: + (Optional) A scalar of type ``LOGICAL``. + + :return: + If :samp:`{DIM}` is absent, the result is a rank-one array with a length + equal to the rank of :samp:`{ARRAY}`. If :samp:`{DIM}` is present, the result + is an array with a rank one less than the rank of :samp:`{ARRAY}`, and a + size corresponding to the size of :samp:`{ARRAY}` with the :samp:`{DIM}` + dimension removed. If :samp:`{DIM}` is present and :samp:`{ARRAY}` has a rank + of one, the result is a scalar. If the optional argument :samp:`{KIND}` + is present, the result is an integer of kind :samp:`{KIND}`, otherwise it + is of default kind. + + Standard: + Fortran 2008 and later. + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK]) + RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK]) + + See also: + :ref:`MAXLOC`, + :ref:`MINLOC`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/floor.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/floor.rst new file mode 100644 index 0000000..7c7eaee --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/floor.rst @@ -0,0 +1,51 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FLOOR, floor, rounding, floor + +.. _floor: + +FLOOR --- Integer floor function +******************************** + +.. function:: FLOOR(A) + + ``FLOOR(A)`` returns the greatest integer less than or equal to :samp:`{X}`. + + :param A: + The type shall be ``REAL``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER(KIND)`` if :samp:`{KIND}` is present + and of default-kind ``INTEGER`` otherwise. + + Standard: + Fortran 95 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = FLOOR(A [, KIND]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`CEILING`, + :ref:`NINT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/flush.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/flush.rst new file mode 100644 index 0000000..c761b35 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/flush.rst @@ -0,0 +1,72 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FLUSH, file operation, flush + +.. _flush: + +FLUSH --- Flush I/O unit(s) +*************************** + +.. function:: FLUSH(UNIT) + + Flushes Fortran unit(s) currently open for output. Without the optional + argument, all units are flushed, otherwise just the unit specified. + + :param UNIT: + (Optional) The type shall be ``INTEGER``. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL FLUSH(UNIT) + + Note: + Beginning with the Fortran 2003 standard, there is a ``FLUSH`` + statement that should be preferred over the ``FLUSH`` intrinsic. + + The ``FLUSH`` intrinsic and the Fortran 2003 ``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 ``fsync`` function, with the POSIX file + descriptor of the I/O unit as argument (retrieved with GNU intrinsic + ``FNUM``). The following example shows how: + + .. code-block:: fortran + + ! 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"
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/fnum.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/fnum.rst new file mode 100644 index 0000000..b756f0a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/fnum.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FNUM, file operation, file number + +.. _fnum: + +FNUM --- File number function +***************************** + +.. function:: FNUM(UNIT) + + ``FNUM(UNIT)`` returns the POSIX file descriptor number corresponding to the + open Fortran I/O unit ``UNIT``. + + :param UNIT: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = FNUM(UNIT) + + Example: + .. code-block:: fortran + + program test_fnum + integer :: i + open (unit=10, status = "scratch") + i = fnum(10) + print *, i + close (10) + end program test_fnum
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/fput.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/fput.rst new file mode 100644 index 0000000..54d1e6c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/fput.rst @@ -0,0 +1,54 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FPUT, write character, stream mode, stream mode, write character, file operation, write character + +.. _fput: + +FPUT --- Write a single character in stream mode to stdout +*********************************************************** + +.. function:: FPUT(C) + + 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. + + :param C: + The type shall be ``CHARACTER`` and of default + kind. + + :param STATUS: + (Optional) status flag of type ``INTEGER``. + Returns 0 on success, -1 on end-of-file and a system specific positive + error code otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL FPUT(C [, STATUS]) + STATUS = FPUT(C) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`FPUTC`, + :ref:`FGET`, + :ref:`FGETC`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/fputc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/fputc.rst new file mode 100644 index 0000000..063c1a8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/fputc.rst @@ -0,0 +1,60 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FPUTC, write character, stream mode, stream mode, write character, file operation, write character + +.. _fputc: + +FPUTC --- Write a single character in stream mode +************************************************* + +.. function:: FPUTC(UNIT, C) + + 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. + + :param UNIT: + The type shall be ``INTEGER``. + + :param C: + The type shall be ``CHARACTER`` and of default + kind. + + :param STATUS: + (Optional) status flag of type ``INTEGER``. + Returns 0 on success, -1 on end-of-file and a system specific positive + error code otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL FPUTC(UNIT, C [, STATUS]) + STATUS = FPUTC(UNIT, C) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`FPUT`, + :ref:`FGET`, + :ref:`FGETC`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/fraction.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/fraction.rst new file mode 100644 index 0000000..4e25863 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/fraction.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FRACTION, real number, fraction, floating point, fraction + +.. _fraction: + +FRACTION --- Fractional part of the model representation +******************************************************** + +.. function:: FRACTION(X) + + ``FRACTION(X)`` returns the fractional part of the model + representation of ``X``. + + :param X: + The type of the argument shall be a ``REAL``. + + :return: + The return value is of the same type and kind as the argument. + The fractional part of the model representation of ``X`` is returned; + it is ``X * RADIX(X)**(-EXPONENT(X))``. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + Y = FRACTION(X) + + Example: + .. code-block:: fortran + + program test_fraction + real :: x + x = 178.1387e-4 + print *, fraction(x), x * radix(x)**(-exponent(x)) + end program test_fraction
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/free.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/free.rst new file mode 100644 index 0000000..9bf7f9a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/free.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FREE, pointer, cray + +.. _free: + +FREE --- Frees memory +********************* + +.. function:: FREE(PTR) + + Frees memory previously allocated by ``MALLOC``. The ``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 + ``DEALLOCATE``. + + :param PTR: + The type shall be ``INTEGER``. It represents the + location of the memory that should be de-allocated. + + :return: + None + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL FREE(PTR) + + Example: + See ``MALLOC`` for an example. + + See also: + :ref:`MALLOC`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/fseek.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/fseek.rst new file mode 100644 index 0000000..cddc4b8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/fseek.rst @@ -0,0 +1,72 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FSEEK, file operation, seek, file operation, position + +.. _fseek: + +FSEEK --- Low level file positioning subroutine +*********************************************** + +.. function:: FSEEK(UNIT, OFFSET, WHENCE, STATUS) + + Moves :samp:`{UNIT}` to the specified :samp:`{OFFSET}`. If :samp:`{WHENCE}` + is set to 0, the :samp:`{OFFSET}` is taken as an absolute value ``SEEK_SET``, + if set to 1, :samp:`{OFFSET}` is taken to be relative to the current position + ``SEEK_CUR``, and if set to 2 relative to the end of the file ``SEEK_END``. + On error, :samp:`{STATUS}` is set to a nonzero value. If :samp:`{STATUS}` the seek + fails silently. + + :param UNIT: + Shall be a scalar of type ``INTEGER``. + + :param OFFSET: + Shall be a scalar of type ``INTEGER``. + + :param WHENCE: + Shall be a scalar of type ``INTEGER``. + Its value shall be either 0, 1 or 2. + + :param STATUS: + (Optional) shall be a scalar of type + ``INTEGER(4)``. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`FTELL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/fstat.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/fstat.rst new file mode 100644 index 0000000..dfd44f8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/fstat.rst @@ -0,0 +1,47 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _fstat: + +FSTAT --- Get file status +************************* + +.. index:: FSTAT, file system, file status + +.. function:: FSTAT(UNIT, VALUES, STATUS) + + ``FSTAT`` is identical to :ref:`STAT`, except that information about an + already opened file is obtained. + + :param UNIT: + An open I/O unit number of type ``INTEGER``. + + :param VALUES: + The type shall be ``INTEGER(4), DIMENSION(13)``. + + :param STATUS: + (Optional) status flag of type ``INTEGER(4)``. Returns 0 + on success and a system specific error code otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL FSTAT(UNIT, VALUES [, STATUS]) + STATUS = FSTAT(UNIT, VALUES) + + Example: + See :ref:`STAT` for an example. + + See also: + To stat a link: + :ref:`LSTAT` + To stat a file: + :ref:`STAT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ftell.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ftell.rst new file mode 100644 index 0000000..fcd0e26 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ftell.rst @@ -0,0 +1,50 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: FTELL, file operation, position + +.. _ftell: + +FTELL --- Current stream position +********************************* + +.. function:: FTELL(UNIT) + + Retrieves the current position within an open file. + + :param OFFSET: + Shall of type ``INTEGER``. + + :param UNIT: + Shall of type ``INTEGER``. + + :return: + In either syntax, :samp:`{OFFSET}` is set to the current offset of unit + number :samp:`{UNIT}`, or to -1 if the unit is not currently open. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL FTELL(UNIT, OFFSET) + OFFSET = FTELL(UNIT) + + Example: + .. code-block:: fortran + + PROGRAM test_ftell + INTEGER :: i + OPEN(10, FILE="temp.dat") + CALL ftell(10,i) + WRITE(*,*) i + END PROGRAM + + See also: + :ref:`FSEEK`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/gamma.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/gamma.rst new file mode 100644 index 0000000..5d58972 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/gamma.rst @@ -0,0 +1,67 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gamma: + +.. index:: GAMMA + +.. index:: DGAMMA + +.. index:: Gamma function + +.. index:: Factorial function + +GAMMA --- Gamma function +************************ + +.. function:: GAMMA(X) + + ``GAMMA(X)`` computes Gamma (\Gamma) of :samp:`{X}`. For positive, + integer values of :samp:`{X}` the Gamma function simplifies to the factorial + function \Gamma(x)=(x-1)!. + + :param X: + Shall be of type ``REAL`` and neither zero + nor a negative integer. + + :return: + The return value is of type ``REAL`` of the same kind as :samp:`{X}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + X = GAMMA(X) + + Example: + .. code-block:: fortran + + program test_gamma + real :: x = 1.0 + x = gamma(x) ! returns 1.0 + end program test_gamma + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DGAMMA(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + + See also: + Logarithm of the Gamma function: + :ref:`LOG_GAMMA`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/gerror.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/gerror.rst new file mode 100644 index 0000000..dedbef7 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/gerror.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GERROR, system, error handling + +.. _gerror: + +GERROR --- Get last system error message +**************************************** + +.. function:: GERROR(RESULT) + + Returns the system error message corresponding to the last system error. + This resembles the functionality of ``strerror(3)`` in C. + + :param RESULT: + Shall be of type ``CHARACTER`` and of default kind. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL GERROR(RESULT) + + Example: + .. code-block:: fortran + + PROGRAM test_gerror + CHARACTER(len=100) :: msg + CALL gerror(msg) + WRITE(*,*) msg + END PROGRAM + + See also: + :ref:`IERRNO`, + :ref:`PERROR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/getarg.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/getarg.rst new file mode 100644 index 0000000..348c03a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/getarg.rst @@ -0,0 +1,64 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GETARG, command-line arguments, arguments, to program + +.. _getarg: + +GETARG --- Get command line arguments +************************************* + +.. function:: GETARG(POS, VALUE) + + Retrieve the :samp:`{POS}` -th argument that was passed on the + command line when the containing program was invoked. + + :param POS: + Shall be of type ``INTEGER`` and not wider than + the default integer kind; :samp:`{POS}` \geq 0 + + :param VALUE: + Shall be of type ``CHARACTER`` and of default + kind. + + :return: + After ``GETARG`` returns, the :samp:`{VALUE}` argument holds the + :samp:`{POS}` th command line argument. If :samp:`{VALUE}` cannot hold the + argument, it is truncated to fit the length of :samp:`{VALUE}`. If there are + less than :samp:`{POS}` arguments specified at the command line, :samp:`{VALUE}` + will be filled with blanks. If :samp:`{POS}` = 0, :samp:`{VALUE}` is set + to the name of the program (on systems that support this feature). + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL GETARG(POS, VALUE) + + Example: + .. code-block:: fortran + + PROGRAM test_getarg + INTEGER :: i + CHARACTER(len=32) :: arg + + DO i = 1, iargc() + CALL getarg(i, arg) + WRITE (*,*) arg + END DO + END PROGRAM + + See also: + GNU Fortran 77 compatibility function: + :ref:`IARGC` + Fortran 2003 functions and subroutines: + :ref:`GET_COMMAND`, + :ref:`GET_COMMAND_ARGUMENT`, + :ref:`COMMAND_ARGUMENT_COUNT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/getcommand.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/getcommand.rst new file mode 100644 index 0000000..9c95999 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/getcommand.rst @@ -0,0 +1,58 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GET_COMMAND, command-line arguments, arguments, to program + +.. _get_command: + +GET_COMMAND --- Get the entire command line +******************************************* + +.. function:: GET_COMMAND(COMMAND, LENGTH, STATUS) + + Retrieve the entire command line that was used to invoke the program. + + :param COMMAND: + (Optional) shall be of type ``CHARACTER`` and + of default kind. + + :param LENGTH: + (Optional) Shall be of type ``INTEGER`` and of + default kind. + + :param STATUS: + (Optional) Shall be of type ``INTEGER`` and of + default kind. + + :return: + If :samp:`{COMMAND}` is present, stores the entire command line that was used + to invoke the program in :samp:`{COMMAND}`. If :samp:`{LENGTH}` is present, it is + assigned the length of the command line. If :samp:`{STATUS}` is present, it + is assigned 0 upon success of the command, -1 if :samp:`{COMMAND}` is too + short to store the command line, or a positive value in case of an error. + + Standard: + Fortran 2003 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL GET_COMMAND([COMMAND, LENGTH, STATUS]) + + Example: + .. code-block:: fortran + + PROGRAM test_get_command + CHARACTER(len=255) :: cmd + CALL get_command(cmd) + WRITE (*,*) TRIM(cmd) + END PROGRAM + + See also: + :ref:`GET_COMMAND_ARGUMENT`, + :ref:`COMMAND_ARGUMENT_COUNT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/getcommandargument.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/getcommandargument.rst new file mode 100644 index 0000000..57c7d56 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/getcommandargument.rst @@ -0,0 +1,76 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GET_COMMAND_ARGUMENT, command-line arguments, arguments, to program + +.. _get_command_argument: + +GET_COMMAND_ARGUMENT --- Get command line arguments +*************************************************** + +.. function:: GET_COMMAND_ARGUMENT(NUMBER , VALUE, LENGTH, STATUS) + + Retrieve the :samp:`{NUMBER}` -th argument that was passed on the + command line when the containing program was invoked. + + :param NUMBER: + Shall be a scalar of type ``INTEGER`` and of + default kind, :samp:`{NUMBER}` \geq 0 + + :param VALUE: + (Optional) Shall be a scalar of type ``CHARACTER`` + and of default kind. + + :param LENGTH: + (Optional) Shall be a scalar of type ``INTEGER`` + and of default kind. + + :param STATUS: + (Optional) Shall be a scalar of type ``INTEGER`` + and of default kind. + + :return: + After ``GET_COMMAND_ARGUMENT`` returns, the :samp:`{VALUE}` argument holds the + :samp:`{NUMBER}` -th command line argument. If :samp:`{VALUE}` cannot hold the argument, it is + truncated to fit the length of :samp:`{VALUE}`. If there are less than :samp:`{NUMBER}` + arguments specified at the command line, :samp:`{VALUE}` will be filled with blanks. + If :samp:`{NUMBER}` = 0, :samp:`{VALUE}` is set to the name of the program (on + systems that support this feature). The :samp:`{LENGTH}` argument contains the + length of the :samp:`{NUMBER}` -th command line argument. If the argument retrieval + fails, :samp:`{STATUS}` is a positive number; if :samp:`{VALUE}` contains a truncated + command line argument, :samp:`{STATUS}` is -1; and otherwise the :samp:`{STATUS}` is + zero. + + Standard: + Fortran 2003 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`GET_COMMAND`, + :ref:`COMMAND_ARGUMENT_COUNT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/getcwd.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/getcwd.rst new file mode 100644 index 0000000..2c22602 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/getcwd.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GETCWD, system, working directory + +.. _getcwd: + +GETCWD --- Get current working directory +**************************************** + +.. function:: GETCWD(C) + + Get current working directory. + + :param C: + The type shall be ``CHARACTER`` and of default kind. + + :param STATUS: + (Optional) status flag. Returns 0 on success, + a system specific and nonzero error code otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL GETCWD(C [, STATUS]) + STATUS = GETCWD(C) + + Example: + .. code-block:: fortran + + PROGRAM test_getcwd + CHARACTER(len=255) :: cwd + CALL getcwd(cwd) + WRITE(*,*) TRIM(cwd) + END PROGRAM + + See also: + :ref:`CHDIR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/getenv.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/getenv.rst new file mode 100644 index 0000000..706d48a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/getenv.rst @@ -0,0 +1,49 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GETENV, environment variable + +.. _getenv: + +GETENV --- Get an environmental variable +**************************************** + +.. function:: GETENV(NAME, VALUE) + + Get the :samp:`{VALUE}` of the environmental variable :samp:`{NAME}`. + + :param NAME: + Shall be of type ``CHARACTER`` and of default kind. + + :param VALUE: + Shall be of type ``CHARACTER`` and of default kind. + + :return: + Stores the value of :samp:`{NAME}` in :samp:`{VALUE}`. If :samp:`{VALUE}` is + not large enough to hold the data, it is truncated. If :samp:`{NAME}` + is not set, :samp:`{VALUE}` will be filled with blanks. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL GETENV(NAME, VALUE) + + Example: + .. code-block:: fortran + + PROGRAM test_getenv + CHARACTER(len=255) :: homedir + CALL getenv("HOME", homedir) + WRITE (*,*) TRIM(homedir) + END PROGRAM + + See also: + :ref:`GET_ENVIRONMENT_VARIABLE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/getenvironmentvariable.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/getenvironmentvariable.rst new file mode 100644 index 0000000..22fec7e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/getenvironmentvariable.rst @@ -0,0 +1,68 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GET_ENVIRONMENT_VARIABLE, environment variable + +.. _get_environment_variable: + +GET_ENVIRONMENT_VARIABLE --- Get an environmental variable +********************************************************** + +.. function:: GET_ENVIRONMENT_VARIABLE(NAME, VALUE, LENGTH, STATUS, TRIM_NAME) + + Get the :samp:`{VALUE}` of the environmental variable :samp:`{NAME}`. + + :param NAME: + Shall be a scalar of type ``CHARACTER`` + and of default kind. + + :param VALUE: + (Optional) Shall be a scalar of type ``CHARACTER`` + and of default kind. + + :param LENGTH: + (Optional) Shall be a scalar of type ``INTEGER`` + and of default kind. + + :param STATUS: + (Optional) Shall be a scalar of type ``INTEGER`` + and of default kind. + + :param TRIM_NAME: + (Optional) Shall be a scalar of type ``LOGICAL`` + and of default kind. + + :return: + Stores the value of :samp:`{NAME}` in :samp:`{VALUE}`. If :samp:`{VALUE}` is + not large enough to hold the data, it is truncated. If :samp:`{NAME}` + is not set, :samp:`{VALUE}` will be filled with blanks. Argument :samp:`{LENGTH}` + contains the length needed for storing the environment variable :samp:`{NAME}` + or zero if it is not present. :samp:`{STATUS}` is -1 if :samp:`{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 :samp:`{STATUS}` is zero. If :samp:`{TRIM_NAME}` is + present with the value ``.FALSE.``, the trailing blanks in :samp:`{NAME}` + are significant; otherwise they are not part of the environment variable + name. + + Standard: + Fortran 2003 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME) + + Example: + .. code-block:: fortran + + PROGRAM test_getenv + CHARACTER(len=255) :: homedir + CALL get_environment_variable("HOME", homedir) + WRITE (*,*) TRIM(homedir) + END PROGRAM
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/getgid.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/getgid.rst new file mode 100644 index 0000000..07fc8e4 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/getgid.rst @@ -0,0 +1,37 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GETGID, system, group ID + +.. _getgid: + +GETGID --- Group ID function +**************************** + +.. function:: GETGID() + + Returns the numerical group ID of the current process. + + :return: + The return value of ``GETGID`` is an ``INTEGER`` of the default + kind. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = GETGID() + + Example: + See ``GETPID`` for an example. + + See also: + :ref:`GETPID`, + :ref:`GETUID`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/getlog.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/getlog.rst new file mode 100644 index 0000000..888f8bb --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/getlog.rst @@ -0,0 +1,47 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GETLOG, system, login name, login name + +.. _getlog: + +GETLOG --- Get login name +************************* + +.. function:: GETLOG(C) + + Gets the username under which the program is running. + + :param C: + Shall be of type ``CHARACTER`` and of default kind. + + :return: + Stores the current user name in :samp:`{C}`. (On systems where POSIX + functions ``geteuid`` and ``getpwuid`` are not available, and + the ``getlogin`` function is not implemented either, this will + return a blank string.) + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL GETLOG(C) + + Example: + .. code-block:: fortran + + PROGRAM TEST_GETLOG + CHARACTER(32) :: login + CALL GETLOG(login) + WRITE(*,*) login + END PROGRAM + + See also: + :ref:`GETUID`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/getpid.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/getpid.rst new file mode 100644 index 0000000..a9a4d83 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/getpid.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GETPID, system, process ID, process ID + +.. _getpid: + +GETPID --- Process ID function +****************************** + +.. function:: GETPID() + + Returns the numerical process identifier of the current process. + + :return: + The return value of ``GETPID`` is an ``INTEGER`` of the default + kind. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = GETPID() + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`GETGID`, + :ref:`GETUID`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/getuid.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/getuid.rst new file mode 100644 index 0000000..ab37b3f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/getuid.rst @@ -0,0 +1,37 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GETUID, system, user ID, user id + +.. _getuid: + +GETUID --- User ID function +*************************** + +.. function:: GETUID() + + Returns the numerical user ID of the current process. + + :return: + The return value of ``GETUID`` is an ``INTEGER`` of the default + kind. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = GETUID() + + Example: + See ``GETPID`` for an example. + + See also: + :ref:`GETPID`, + :ref:`GETLOG`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/gmtime.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/gmtime.rst new file mode 100644 index 0000000..35b24c4 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/gmtime.rst @@ -0,0 +1,47 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: GMTIME, time, conversion to GMT info + +.. _gmtime: + +GMTIME --- Convert time to GMT info +*********************************** + +.. function:: GMTIME(TIME, VALUES) + + Given a system time value :samp:`{TIME}` (as provided by the :ref:`TIME` + intrinsic), fills :samp:`{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 ``gmtime(3)``. + + :param TIME: + An ``INTEGER`` scalar expression + corresponding to a system time, with ``INTENT(IN)``. + + :param VALUES: + A default ``INTEGER`` array with 9 elements, + with ``INTENT(OUT)``. + + :return: + The elements of :samp:`{VALUES}` are assigned as follows: + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL GMTIME(TIME, VALUES) + + See also: + :ref:`DATE_AND_TIME`, + :ref:`CTIME`, + :ref:`LTIME`, + :ref:`TIME`, + :ref:`TIME8`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/hostnm.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/hostnm.rst new file mode 100644 index 0000000..319f094 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/hostnm.rst @@ -0,0 +1,38 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: HOSTNM, system, host name + +.. _hostnm: + +HOSTNM --- Get system host name +******************************* + +.. function:: HOSTNM(NAME) + + Retrieves the host name of the system on which the program is running. + + :param C: + Shall of type ``CHARACTER`` and of default kind. + + :param STATUS: + (Optional) status flag of type ``INTEGER``. + Returns 0 on success, or a system specific error code otherwise. + + :return: + In either syntax, :samp:`{NAME}` is set to the current hostname if it can + be obtained, or to a blank string otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL HOSTNM(C [, STATUS]) + STATUS = HOSTNM(NAME)
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/huge.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/huge.rst new file mode 100644 index 0000000..6f7fec8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/huge.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: HUGE, limits, largest number, model representation, largest number + +.. _huge: + +HUGE --- Largest number of a kind +********************************* + +.. function:: HUGE(X) + + ``HUGE(X)`` returns the largest number that is not an infinity in + the model of the type of ``X``. + + :param X: + Shall be of type ``REAL`` or ``INTEGER``. + + :return: + The return value is of the same type and kind as :samp:`{X}` + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = HUGE(X) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/hypot.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/hypot.rst new file mode 100644 index 0000000..f567cc1 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/hypot.rst @@ -0,0 +1,45 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: HYPOT, Euclidean distance + +.. _hypot: + +HYPOT --- Euclidean distance function +************************************* + +.. function:: HYPOT(X,Y) + + ``HYPOT(X,Y)`` is the Euclidean distance function. It is equal to + \sqrt{X^2 + Y^2}, without undue underflow or overflow. + + :param X: + The type shall be ``REAL``. + + :param Y: + The type and kind type parameter shall be the same as + :samp:`{X}`. + + :return: + The return value has the same type and kind type parameter as :samp:`{X}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = HYPOT(X, Y) + + Example: + .. code-block:: fortran + + program test_hypot + real(4) :: x = 1.e0_4, y = 0.5e0_4 + x = hypot(x,y) + end program test_hypot
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/iachar.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/iachar.rst new file mode 100644 index 0000000..edc94e6 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/iachar.rst @@ -0,0 +1,55 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: IACHAR, ASCII collating sequence, collating sequence, ASCII, conversion, to integer + +.. _iachar: + +IACHAR --- Code in ASCII collating sequence +******************************************** + +.. function:: IACHAR(C) + + ``IACHAR(C)`` returns the code for the ASCII character + in the first character position of ``C``. + + :param C: + Shall be a scalar ``CHARACTER``, with ``INTENT(IN)`` + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + + Standard: + Fortran 95 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = IACHAR(C [, KIND]) + + Example: + .. code-block:: fortran + + program test_iachar + integer i + i = iachar(' ') + end program test_iachar + + Note: + See :ref:`ICHAR` for a discussion of converting between numerical values + and formatted string representations. + + See also: + :ref:`ACHAR`, + :ref:`CHAR`, + :ref:`ICHAR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/iall.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/iall.rst new file mode 100644 index 0000000..2f6a41d --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/iall.rst @@ -0,0 +1,61 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: IALL, array, AND, bits, AND of array elements + +.. _iall: + +IALL --- Bitwise AND of array elements +************************************** + +.. function:: IALL(ARRAY, DIM, MASK) + + Reduces with bitwise AND the elements of :samp:`{ARRAY}` along dimension :samp:`{DIM}` + if the corresponding element in :samp:`{MASK}` is ``TRUE``. + + :param ARRAY: + Shall be an array of type ``INTEGER`` + + :param DIM: + (Optional) shall be a scalar of type + ``INTEGER`` with a value in the range from 1 to n, where n + equals the rank of :samp:`{ARRAY}`. + + :param MASK: + (Optional) shall be of type ``LOGICAL`` + and either be a scalar or an array of the same shape as :samp:`{ARRAY}`. + + :return: + The result is of the same type as :samp:`{ARRAY}`. + + Standard: + Fortran 2008 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = IALL(ARRAY[, MASK]) + RESULT = IALL(ARRAY, DIM[, MASK]) + + Example: + .. code-block:: fortran + + PROGRAM test_iall + INTEGER(1) :: a(2) + + a(1) = b'00100100' + a(2) = b'01101010' + + ! prints 00100000 + PRINT '(b8.8)', IALL(a) + END PROGRAM + + See also: + :ref:`IANY`, + :ref:`IPARITY`, + :ref:`IAND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/iand.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/iand.rst new file mode 100644 index 0000000..804ce5e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/iand.rst @@ -0,0 +1,99 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _iand: + +.. index:: IAND + +.. index:: BIAND + +.. index:: IIAND + +.. index:: JIAND + +.. index:: KIAND + +.. index:: bitwise logical and + +.. index:: logical and, bitwise + +IAND --- Bitwise logical and +**************************** + +.. function:: IAND(I, J) + + Bitwise logical ``AND``. + + :param I: + The type shall be ``INTEGER`` or a boz-literal-constant. + + :param J: + The type shall be ``INTEGER`` with the same + kind type parameter as :samp:`{I}` or a boz-literal-constant. + :samp:`{I}` and :samp:`{J}` shall not both be boz-literal-constants. + + :return: + The return type is ``INTEGER`` with the kind type parameter of the + arguments. + A boz-literal-constant is converted to an ``INTEGER`` with the kind + type parameter of the other argument as-if a call to :ref:`INT` occurred. + + Standard: + Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = IAND(I, J) + + Example: + .. code-block:: fortran + + PROGRAM test_iand + INTEGER :: a, b + DATA a / Z'F' /, b / Z'3' / + WRITE (*,*) IAND(a, b) + END PROGRAM + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``IAND(A)`` + - ``INTEGER A`` + - ``INTEGER`` + - Fortran 90 and later + * - ``BIAND(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``IIAND(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JIAND(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KIAND(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`IOR`, + :ref:`IEOR`, + :ref:`IBITS`, + :ref:`IBSET`, + :ref:`IBCLR`, + :ref:`NOT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/iany.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/iany.rst new file mode 100644 index 0000000..523b04e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/iany.rst @@ -0,0 +1,61 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: IANY, array, OR, bits, OR of array elements + +.. _iany: + +IANY --- Bitwise OR of array elements +************************************* + +.. function:: IANY(ARRAY, DIM, MASK) + + Reduces with bitwise OR (inclusive or) the elements of :samp:`{ARRAY}` along + dimension :samp:`{DIM}` if the corresponding element in :samp:`{MASK}` is ``TRUE``. + + :param ARRAY: + Shall be an array of type ``INTEGER`` + + :param DIM: + (Optional) shall be a scalar of type + ``INTEGER`` with a value in the range from 1 to n, where n + equals the rank of :samp:`{ARRAY}`. + + :param MASK: + (Optional) shall be of type ``LOGICAL`` + and either be a scalar or an array of the same shape as :samp:`{ARRAY}`. + + :return: + The result is of the same type as :samp:`{ARRAY}`. + + Standard: + Fortran 2008 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = IANY(ARRAY[, MASK]) + RESULT = IANY(ARRAY, DIM[, MASK]) + + Example: + .. code-block:: fortran + + PROGRAM test_iany + INTEGER(1) :: a(2) + + a(1) = b'00100100' + a(2) = b'01101010' + + ! prints 01101110 + PRINT '(b8.8)', IANY(a) + END PROGRAM + + See also: + :ref:`IPARITY`, + :ref:`IALL`, + :ref:`IOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/iargc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/iargc.rst new file mode 100644 index 0000000..6242b13 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/iargc.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _iargc: + +IARGC --- Get the number of command line arguments +************************************************** + +.. index:: IARGC, command-line arguments, command-line arguments, number of, arguments, to program + +.. function:: IARGC() + + ``IARGC`` returns the number of arguments passed on the + command line when the containing program was invoked. + + :return: + The number of command line arguments, type ``INTEGER(4)``. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = IARGC() + + Arguments: + None + + Example: + See :ref:`GETARG` + + See also: + GNU Fortran 77 compatibility subroutine: + :ref:`GETARG` + Fortran 2003 functions and subroutines: + :ref:`GET_COMMAND`, + :ref:`GET_COMMAND_ARGUMENT`, + :ref:`COMMAND_ARGUMENT_COUNT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ibclr.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ibclr.rst new file mode 100644 index 0000000..44be678 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ibclr.rst @@ -0,0 +1,87 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ibclr: + +.. index:: IBCLR + +.. index:: BBCLR + +.. index:: IIBCLR + +.. index:: JIBCLR + +.. index:: KIBCLR + +.. index:: bits, unset + +.. index:: bits, clear + +IBCLR --- Clear bit +******************* + +.. function:: IBCLR() + + ``IBCLR`` returns the value of :samp:`{I}` with the bit at position + :samp:`{POS}` set to zero. + + :param I: + The type shall be ``INTEGER``. + + :param POS: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the same kind as + :samp:`{I}`. + + Standard: + Fortran 90 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = IBCLR(I, POS) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``IBCLR(A)`` + - ``INTEGER A`` + - ``INTEGER`` + - Fortran 90 and later + * - ``BBCLR(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``IIBCLR(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JIBCLR(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KIBCLR(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`IBITS`, + :ref:`IBSET`, + :ref:`IAND`, + :ref:`IOR`, + :ref:`IEOR`, + :ref:`MVBITS`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ibits.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ibits.rst new file mode 100644 index 0000000..9c14634 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ibits.rst @@ -0,0 +1,93 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ibits: + +.. index:: IBITS + +.. index:: BBITS + +.. index:: IIBITS + +.. index:: JIBITS + +.. index:: KIBITS + +.. index:: bits, get + +.. index:: bits, extract + +IBITS --- Bit extraction +************************ + +.. function:: IBITS() + + ``IBITS`` extracts a field of length :samp:`{LEN}` from :samp:`{I}`, + starting from bit position :samp:`{POS}` and extending left for :samp:`{LEN}` + bits. The result is right-justified and the remaining bits are + zeroed. The value of ``POS+LEN`` must be less than or equal to the + value ``BIT_SIZE(I)``. + + :param I: + The type shall be ``INTEGER``. + + :param POS: + The type shall be ``INTEGER``. + + :param LEN: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the same kind as + :samp:`{I}`. + + Standard: + Fortran 90 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = IBITS(I, POS, LEN) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``IBITS(A)`` + - ``INTEGER A`` + - ``INTEGER`` + - Fortran 90 and later + * - ``BBITS(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``IIBITS(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JIBITS(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KIBITS(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`BIT_SIZE`, + :ref:`IBCLR`, + :ref:`IBSET`, + :ref:`IAND`, + :ref:`IOR`, + :ref:`IEOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ibset.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ibset.rst new file mode 100644 index 0000000..502947f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ibset.rst @@ -0,0 +1,85 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ibset: + +.. index:: IBSET + +.. index:: BBSET + +.. index:: IIBSET + +.. index:: JIBSET + +.. index:: KIBSET + +.. index:: bits, set + +IBSET --- Set bit +***************** + +.. function:: IBSET() + + ``IBSET`` returns the value of :samp:`{I}` with the bit at position + :samp:`{POS}` set to one. + + :param I: + The type shall be ``INTEGER``. + + :param POS: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the same kind as + :samp:`{I}`. + + Standard: + Fortran 90 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = IBSET(I, POS) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``IBSET(A)`` + - ``INTEGER A`` + - ``INTEGER`` + - Fortran 90 and later + * - ``BBSET(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``IIBSET(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JIBSET(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KIBSET(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`IBCLR`, + :ref:`IBITS`, + :ref:`IAND`, + :ref:`IOR`, + :ref:`IEOR`, + :ref:`MVBITS`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ichar.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ichar.rst new file mode 100644 index 0000000..3ff689e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ichar.rst @@ -0,0 +1,93 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ichar: + +.. index:: ICHAR + +.. index:: conversion, to integer + +ICHAR --- Character-to-integer conversion function +************************************************** + +.. function:: ICHAR(C) + + ``ICHAR(C)`` returns the code for the character in the first character + position of ``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. + + :param C: + Shall be a scalar ``CHARACTER``, with ``INTENT(IN)`` + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + + Standard: + Fortran 77 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ICHAR(C [, KIND]) + + Example: + .. code-block:: fortran + + program test_ichar + integer i + i = ichar(' ') + end program test_ichar + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ICHAR(C)`` + - ``CHARACTER C`` + - ``INTEGER(4)`` + - Fortran 77 and later + + Note: + No intrinsic exists to convert between a numeric value and a formatted + character string representation -- for instance, given the + ``CHARACTER`` value ``'154'``, obtaining an ``INTEGER`` or + ``REAL`` value with the value 154, or vice versa. Instead, this + functionality is provided by internal-file I/O, as in the following + example: + + .. code-block:: fortran + + 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 + + See also: + :ref:`ACHAR`, + :ref:`CHAR`, + :ref:`IACHAR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/idate.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/idate.rst new file mode 100644 index 0000000..798e115 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/idate.rst @@ -0,0 +1,50 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: IDATE, date, current, current date + +.. _idate: + +IDATE --- Get current local time subroutine (day/month/year) +************************************************************* + +.. function:: IDATE(VALUES) + + ``IDATE(VALUES)`` Fills :samp:`{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 :samp:`{VALUES}`, respectively. + The year has four significant digits. + + :param VALUES: + The type shall be ``INTEGER, DIMENSION(3)`` and + the kind shall be the default integer kind. + + :return: + Does not return anything. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL IDATE(VALUES) + + Example: + .. code-block:: fortran + + program test_idate + integer, dimension(3) :: tarray + call idate(tarray) + print *, tarray(1) + print *, tarray(2) + print *, tarray(3) + end program test_idate + + See also: + :ref:`DATE_AND_TIME`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ieor.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ieor.rst new file mode 100644 index 0000000..79d6a3d --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ieor.rst @@ -0,0 +1,91 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ieor: + +.. index:: IEOR + +.. index:: BIEOR + +.. index:: IIEOR + +.. index:: JIEOR + +.. index:: KIEOR + +.. index:: bitwise logical exclusive or + +.. index:: logical exclusive or, bitwise + +IEOR --- Bitwise logical exclusive or +************************************* + +.. function:: IEOR() + + ``IEOR`` returns the bitwise Boolean exclusive-OR of :samp:`{I}` and + :samp:`{J}`. + + :param I: + The type shall be ``INTEGER`` or a boz-literal-constant. + + :param J: + The type shall be ``INTEGER`` with the same + kind type parameter as :samp:`{I}` or a boz-literal-constant. + :samp:`{I}` and :samp:`{J}` shall not both be boz-literal-constants. + + :return: + The return type is ``INTEGER`` with the kind type parameter of the + arguments. + A boz-literal-constant is converted to an ``INTEGER`` with the kind + type parameter of the other argument as-if a call to :ref:`INT` occurred. + + Standard: + Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = IEOR(I, J) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``IEOR(A)`` + - ``INTEGER A`` + - ``INTEGER`` + - Fortran 90 and later + * - ``BIEOR(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``IIEOR(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JIEOR(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KIEOR(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`IOR`, + :ref:`IAND`, + :ref:`IBITS`, + :ref:`IBSET`, + :ref:`IBCLR`, + :ref:`NOT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ierrno.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ierrno.rst new file mode 100644 index 0000000..fbeff17 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ierrno.rst @@ -0,0 +1,37 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: IERRNO, system, error handling + +.. _ierrno: + +IERRNO --- Get the last system error number +******************************************* + +.. function:: IERRNO() + + Returns the last system error number, as given by the C ``errno`` + variable. + + :return: + The return value is of type ``INTEGER`` and of the default integer + kind. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = IERRNO() + + Arguments: + None + + See also: + :ref:`PERROR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/imageindex.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/imageindex.rst new file mode 100644 index 0000000..7f28957 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/imageindex.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: IMAGE_INDEX, coarray, IMAGE_INDEX, images, cosubscript to image index conversion + +.. _image_index: + +IMAGE_INDEX --- Function that converts a cosubscript to an image index +********************************************************************** + +.. function:: IMAGE_INDEX(COARRAY, SUB) + + Returns the image index belonging to a cosubscript. + + :param COARRAY: + Coarray of any type. + + :param SUB: + default integer rank-1 array of a size equal to + the corank of :samp:`{COARRAY}`. + + :return: + Scalar default integer with the value of the image index which corresponds + to the cosubscripts. For invalid cosubscripts the result is zero. + + Standard: + Fortran 2008 and later + + Class: + Inquiry function. + + Syntax: + .. code-block:: fortran + + RESULT = IMAGE_INDEX(COARRAY, SUB) + + Example: + .. code-block:: fortran + + 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]) + + See also: + :ref:`THIS_IMAGE`, + :ref:`NUM_IMAGES`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/index.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/index.rst new file mode 100644 index 0000000..969aa61 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/index.rst @@ -0,0 +1,72 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _index-intrinsic: + +.. index:: INDEX + +.. index:: substring position + +.. index:: string, find substring + +INDEX --- Position of a substring within a string +************************************************* + +.. function:: INDEX(STRING, SUBSTRING , BACK , KIND) + + Returns the position of the start of the first occurrence of string + :samp:`{SUBSTRING}` as a substring in :samp:`{STRING}`, counting from one. If + :samp:`{SUBSTRING}` is not present in :samp:`{STRING}`, zero is returned. If + the :samp:`{BACK}` argument is present and true, the return value is the + start of the last occurrence rather than the first. + + :param STRING: + Shall be a scalar ``CHARACTER``, with + ``INTENT(IN)`` + + :param SUBSTRING: + Shall be a scalar ``CHARACTER``, with + ``INTENT(IN)`` + + :param BACK: + (Optional) Shall be a scalar ``LOGICAL``, with + ``INTENT(IN)`` + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + + Standard: + Fortran 77 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]]) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``INDEX(STRING,SUBSTRING)`` + - ``CHARACTER`` + - ``INTEGER(4)`` + - Fortran 77 and later + + See also: + :ref:`SCAN`, + :ref:`VERIFY`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/int.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/int.rst new file mode 100644 index 0000000..43d2a56 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/int.rst @@ -0,0 +1,76 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _int: + +.. index:: INT + +.. index:: IFIX + +.. index:: IDINT + +.. index:: conversion, to integer + +INT --- Convert to integer type +******************************* + +.. function:: INT(A , KIND)) + + Convert to integer type + + :param A: + Shall be of type ``INTEGER``, + ``REAL``, or ``COMPLEX`` or a boz-literal-constant. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + These functions return a ``INTEGER`` variable or array under + the following rules: + + Standard: + Fortran 77 and later, with boz-literal-constant Fortran 2008 and later. + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = INT(A [, KIND)) + + Example: + .. code-block:: fortran + + program test_int + integer :: i = 42 + complex :: z = (-3.7, 1.0) + print *, int(i) + print *, int(z), int(z,8) + end program + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``INT(A)`` + - ``REAL(4) A`` + - ``INTEGER`` + - Fortran 77 and later + * - ``IFIX(A)`` + - ``REAL(4) A`` + - ``INTEGER`` + - Fortran 77 and later + * - ``IDINT(A)`` + - ``REAL(8) A`` + - ``INTEGER`` + - Fortran 77 and later
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/int2.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/int2.rst new file mode 100644 index 0000000..e650dd1 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/int2.rst @@ -0,0 +1,39 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: INT2, conversion, to integer + +.. _int2: + +INT2 --- Convert to 16-bit integer type +*************************************** + +.. function:: INT2(A) + + Convert to a ``KIND=2`` integer type. This is equivalent to the + standard ``INT`` intrinsic with an optional argument of + ``KIND=2``, and is only included for backwards compatibility. + + :param A: + Shall be of type ``INTEGER``, + ``REAL``, or ``COMPLEX``. + + :return: + The return value is a ``INTEGER(2)`` variable. + + Standard: + GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = INT2(A) + + See also: + :ref:`INT`, + :ref:`INT8`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/int8.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/int8.rst new file mode 100644 index 0000000..cb061a5 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/int8.rst @@ -0,0 +1,39 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: INT8, conversion, to integer + +.. _int8: + +INT8 --- Convert to 64-bit integer type +*************************************** + +.. function:: INT8(A) + + Convert to a ``KIND=8`` integer type. This is equivalent to the + standard ``INT`` intrinsic with an optional argument of + ``KIND=8``, and is only included for backwards compatibility. + + :param A: + Shall be of type ``INTEGER``, + ``REAL``, or ``COMPLEX``. + + :return: + The return value is a ``INTEGER(8)`` variable. + + Standard: + GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = INT8(A) + + See also: + :ref:`INT`, + :ref:`INT2`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/introduction-to-intrinsic-procedures.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/introduction-to-intrinsic-procedures.rst new file mode 100644 index 0000000..926e1b2 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/introduction-to-intrinsic-procedures.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _introduction-to-intrinsics: + +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 ``KIND`` type parameter is processor defined in +the Fortran 95 standard. GNU Fortran defines the default integer type and +default real type by ``INTEGER(KIND=4)`` and ``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 ``KIND=8``. +Hence, ``REAL(KIND=8)`` and ``DOUBLE PRECISION`` are equivalent. +In the description of generic intrinsic procedures, the kind type parameter +will be specified by ``KIND=*``, and in the description of specific +names for an intrinsic procedure the kind type parameter will be explicitly +given (e.g., ``REAL(KIND=4)`` or ``REAL(KIND=8)``). Finally, for +brevity the optional ``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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ior.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ior.rst new file mode 100644 index 0000000..f210688 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ior.rst @@ -0,0 +1,91 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ior: + +.. index:: IOR + +.. index:: BIOR + +.. index:: IIOR + +.. index:: JIOR + +.. index:: KIOR + +.. index:: bitwise logical or + +.. index:: logical or, bitwise + +IOR --- Bitwise logical or +************************** + +.. function:: IOR() + + ``IOR`` returns the bitwise Boolean inclusive-OR of :samp:`{I}` and + :samp:`{J}`. + + :param I: + The type shall be ``INTEGER`` or a boz-literal-constant. + + :param J: + The type shall be ``INTEGER`` with the same + kind type parameter as :samp:`{I}` or a boz-literal-constant. + :samp:`{I}` and :samp:`{J}` shall not both be boz-literal-constants. + + :return: + The return type is ``INTEGER`` with the kind type parameter of the + arguments. + A boz-literal-constant is converted to an ``INTEGER`` with the kind + type parameter of the other argument as-if a call to :ref:`INT` occurred. + + Standard: + Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = IOR(I, J) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``IOR(A)`` + - ``INTEGER A`` + - ``INTEGER`` + - Fortran 90 and later + * - ``BIOR(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``IIOR(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JIOR(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KIOR(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`IEOR`, + :ref:`IAND`, + :ref:`IBITS`, + :ref:`IBSET`, + :ref:`IBCLR`, + :ref:`NOT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/iparity.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/iparity.rst new file mode 100644 index 0000000..5abd4e1 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/iparity.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: IPARITY, array, parity, array, XOR, bits, XOR of array elements + +.. _iparity: + +IPARITY --- Bitwise XOR of array elements +***************************************** + +.. function:: IPARITY(ARRAY, DIM, MASK) + + Reduces with bitwise XOR (exclusive or) the elements of :samp:`{ARRAY}` along + dimension :samp:`{DIM}` if the corresponding element in :samp:`{MASK}` is ``TRUE``. + + :param ARRAY: + Shall be an array of type ``INTEGER`` + + :param DIM: + (Optional) shall be a scalar of type + ``INTEGER`` with a value in the range from 1 to n, where n + equals the rank of :samp:`{ARRAY}`. + + :param MASK: + (Optional) shall be of type ``LOGICAL`` + and either be a scalar or an array of the same shape as :samp:`{ARRAY}`. + + :return: + The result is of the same type as :samp:`{ARRAY}`. + + Standard: + Fortran 2008 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = IPARITY(ARRAY[, MASK]) + RESULT = IPARITY(ARRAY, DIM[, MASK]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`IANY`, + :ref:`IALL`, + :ref:`IEOR`, + :ref:`PARITY`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/irand.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/irand.rst new file mode 100644 index 0000000..b7b0a69 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/irand.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: IRAND, random number generation + +.. _irand: + +IRAND --- Integer pseudo-random number +************************************** + +.. function:: IRAND(FLAG) + + ``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 :samp:`{FLAG}` is 0, the next number + in the current sequence is returned; if :samp:`{FLAG}` is 1, the generator + is restarted by ``CALL SRAND(0)`` ; if :samp:`{FLAG}` has any other value, + it is used as a new seed with ``SRAND``. + + :param I: + Shall be a scalar ``INTEGER`` of kind 4. + + :return: + The return value is of ``INTEGER(kind=4)`` type. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = IRAND(I) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/isatty.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/isatty.rst new file mode 100644 index 0000000..6b0ef21 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/isatty.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ISATTY, system, terminal + +.. _isatty: + +ISATTY --- Whether a unit is a terminal device +********************************************** + +.. function:: ISATTY(UNIT) + + Determine whether a unit is connected to a terminal device. + + :param UNIT: + Shall be a scalar ``INTEGER``. + + :return: + Returns ``.TRUE.`` if the :samp:`{UNIT}` is connected to a terminal + device, ``.FALSE.`` otherwise. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = ISATTY(UNIT) + + Example: + .. code-block:: fortran + + PROGRAM test_isatty + INTEGER(kind=1) :: unit + DO unit = 1, 10 + write(*,*) isatty(unit=unit) + END DO + END PROGRAM + + See also: + :ref:`TTYNAM`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/iscontiguous.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/iscontiguous.rst new file mode 100644 index 0000000..b7d84ee --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/iscontiguous.rst @@ -0,0 +1,52 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _is_contiguous: + +IS_CONTIGUOUS --- Test whether an array is contiguous +***************************************************** + +.. index:: IS_IOSTAT_EOR, array, contiguity + +.. function:: IS_CONTIGUOUS(ARRAY) + + ``IS_CONTIGUOUS`` tests whether an array is contiguous. + + :param ARRAY: + Shall be an array of any type. + + :return: + Returns a ``LOGICAL`` of the default kind, which ``.TRUE.`` if + :samp:`{ARRAY}` is contiguous and false otherwise. + + Standard: + Fortran 2008 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = IS_CONTIGUOUS(ARRAY) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ishft.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ishft.rst new file mode 100644 index 0000000..c5427f2 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ishft.rst @@ -0,0 +1,85 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ishft: + +.. index:: ISHFT + +.. index:: BSHFT + +.. index:: IISHFT + +.. index:: JISHFT + +.. index:: KISHFT + +.. index:: bits, shift + +ISHFT --- Shift bits +******************** + +.. function:: ISHFT() + + ``ISHFT`` returns a value corresponding to :samp:`{I}` with all of the + bits shifted :samp:`{SHIFT}` places. A value of :samp:`{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 :samp:`{SHIFT}` is greater than ``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. + + :param I: + The type shall be ``INTEGER``. + + :param SHIFT: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the same kind as + :samp:`{I}`. + + Standard: + Fortran 90 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ISHFT(I, SHIFT) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ISHFT(A)`` + - ``INTEGER A`` + - ``INTEGER`` + - Fortran 90 and later + * - ``BSHFT(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``IISHFT(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JISHFT(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KISHFT(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`ISHFTC`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ishftc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ishftc.rst new file mode 100644 index 0000000..f3e1545 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ishftc.rst @@ -0,0 +1,91 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ishftc: + +.. index:: ISHFTC + +.. index:: BSHFTC + +.. index:: IISHFTC + +.. index:: JISHFTC + +.. index:: KISHFTC + +.. index:: bits, shift circular + +ISHFTC --- Shift bits circularly +******************************** + +.. function:: ISHFTC() + + ``ISHFTC`` returns a value corresponding to :samp:`{I}` with the + rightmost :samp:`{SIZE}` bits shifted circularly :samp:`{SHIFT}` places; that + is, bits shifted out one end are shifted into the opposite end. A value + of :samp:`{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 :samp:`{SHIFT}` must be less than + :samp:`{SIZE}`. If the :samp:`{SIZE}` argument is omitted, it is taken to be + equivalent to ``BIT_SIZE(I)``. + + :param I: + The type shall be ``INTEGER``. + + :param SHIFT: + The type shall be ``INTEGER``. + + :param SIZE: + (Optional) The type shall be ``INTEGER`` ; + the value must be greater than zero and less than or equal to + ``BIT_SIZE(I)``. + + :return: + The return value is of type ``INTEGER`` and of the same kind as + :samp:`{I}`. + + Standard: + Fortran 90 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = ISHFTC(I, SHIFT [, SIZE]) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ISHFTC(A)`` + - ``INTEGER A`` + - ``INTEGER`` + - Fortran 90 and later + * - ``BSHFTC(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``IISHFTC(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JISHFTC(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KISHFTC(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`ISHFT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/isiostatend.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/isiostatend.rst new file mode 100644 index 0000000..5efd232 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/isiostatend.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _is_iostat_end: + +IS_IOSTAT_END --- Test for end-of-file value +******************************************** + +.. index:: IS_IOSTAT_END, IOSTAT, end of file + +.. function:: IS_IOSTAT_END(I) + + ``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 ``IOSTAT_END`` parameter of the intrinsic module + ``ISO_FORTRAN_ENV``. + + :param I: + Shall be of the type ``INTEGER``. + + :return: + Returns a ``LOGICAL`` of the default kind, which ``.TRUE.`` if + :samp:`{I}` has the value which indicates an end of file condition for + ``IOSTAT=`` specifiers, and is ``.FALSE.`` otherwise. + + Standard: + Fortran 2003 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = IS_IOSTAT_END(I) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/isiostateor.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/isiostateor.rst new file mode 100644 index 0000000..bafc67f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/isiostateor.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _is_iostat_eor: + +IS_IOSTAT_EOR --- Test for end-of-record value +********************************************** + +.. index:: IS_IOSTAT_EOR, IOSTAT, end of record + +.. function:: IS_IOSTAT_EOR(I) + + ``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 ``IOSTAT_EOR`` parameter of the intrinsic module + ``ISO_FORTRAN_ENV``. + + :param I: + Shall be of the type ``INTEGER``. + + :return: + Returns a ``LOGICAL`` of the default kind, which ``.TRUE.`` if + :samp:`{I}` has the value which indicates an end of file condition for + ``IOSTAT=`` specifiers, and is ``.FALSE.`` otherwise. + + Standard: + Fortran 2003 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = IS_IOSTAT_EOR(I) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/isnan.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/isnan.rst new file mode 100644 index 0000000..312e1db --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/isnan.rst @@ -0,0 +1,45 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _isnan: + +ISNAN --- Test for a NaN +************************ + +.. index:: ISNAN, IEEE, ISNAN + +.. function:: ISNAN(X) + + ``ISNAN`` tests whether a floating-point value is an IEEE + Not-a-Number (NaN). + + :param X: + Variable of the type ``REAL``. + + :return: + Returns a default-kind ``LOGICAL``. The returned value is ``TRUE`` + if :samp:`{X}` is a NaN and ``FALSE`` otherwise. + + Standard: + GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + ISNAN(X) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/itime.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/itime.rst new file mode 100644 index 0000000..4fb25b2 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/itime.rst @@ -0,0 +1,50 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: ITIME, time, current, current time + +.. _itime: + +ITIME --- Get current local time subroutine (hour/minutes/seconds) +******************************************************************* + +.. function:: ITIME(VALUES) + + ``ITIME(VALUES)`` Fills :samp:`{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 :samp:`{VALUES}`, + respectively. + + :param VALUES: + The type shall be ``INTEGER, DIMENSION(3)`` + and the kind shall be the default integer kind. + + :return: + Does not return anything. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL ITIME(VALUES) + + Example: + .. code-block:: fortran + + program test_itime + integer, dimension(3) :: tarray + call itime(tarray) + print *, tarray(1) + print *, tarray(2) + print *, tarray(3) + end program test_itime + + See also: + :ref:`DATE_AND_TIME`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/kill.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/kill.rst new file mode 100644 index 0000000..9ffa4ca --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/kill.rst @@ -0,0 +1,51 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: KILL + +.. _kill: + +KILL --- Send a signal to a process +*********************************** + +.. function:: KILL(PID, SIG) + + Sends the signal specified by :samp:`{SIG}` to the process :samp:`{PID}`. + See ``kill(2)``. + + :param PID: + Shall be a scalar ``INTEGER`` with ``INTENT(IN)``. + + :param SIG: + Shall be a scalar ``INTEGER`` with ``INTENT(IN)``. + + :param STATUS: + [Subroutine](Optional) + Shall be a scalar ``INTEGER``. + Returns 0 on success; otherwise a system-specific error code is returned. + + :param STATUS: + [Function] The kind type parameter is that of + ``pid``. + Returns 0 on success; otherwise a system-specific error code is returned. + + Standard: + GNU extension + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL KILL(PID, SIG [, STATUS]) + STATUS = KILL(PID, SIG) + + See also: + :ref:`ABORT`, + :ref:`EXIT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/kind.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/kind.rst new file mode 100644 index 0000000..594ce10 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/kind.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: KIND, kind + +.. _kind: + +KIND --- Kind of an entity +************************** + +.. function:: KIND(X) + + ``KIND(X)`` returns the kind value of the entity :samp:`{X}`. + + :param X: + Shall be of type ``LOGICAL``, ``INTEGER``, + ``REAL``, ``COMPLEX`` or ``CHARACTER``. It may be scalar or + array valued. + + :return: + The return value is a scalar of type ``INTEGER`` and of the default + integer kind. + + Standard: + Fortran 95 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + K = KIND(X) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/lbound.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/lbound.rst new file mode 100644 index 0000000..d07e972 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/lbound.rst @@ -0,0 +1,51 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: LBOUND, array, lower bound + +.. _lbound: + +LBOUND --- Lower dimension bounds of an array +********************************************* + +.. function:: LBOUND(ARRAY , DIM , KIND) + + Returns the lower bounds of an array, or a single lower bound + along the :samp:`{DIM}` dimension. + + :param ARRAY: + Shall be an array, of any type. + + :param DIM: + (Optional) Shall be a scalar ``INTEGER``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + If :samp:`{DIM}` is absent, the result is an array of the lower bounds of + :samp:`{ARRAY}`. If :samp:`{DIM}` is present, the result is a scalar + corresponding to the lower bound of the array along that dimension. If + :samp:`{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. + + Standard: + Fortran 90 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = LBOUND(ARRAY [, DIM [, KIND]]) + + See also: + :ref:`UBOUND`, + :ref:`LCOBOUND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/lcobound.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/lcobound.rst new file mode 100644 index 0000000..eb99816 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/lcobound.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: LCOBOUND, coarray, lower bound + +.. _lcobound: + +LCOBOUND --- Lower codimension bounds of an array +************************************************* + +.. function:: LCOBOUND(COARRAY , DIM , KIND) + + Returns the lower bounds of a coarray, or a single lower cobound + along the :samp:`{DIM}` codimension. + + :param ARRAY: + Shall be an coarray, of any type. + + :param DIM: + (Optional) Shall be a scalar ``INTEGER``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + If :samp:`{DIM}` is absent, the result is an array of the lower cobounds of + :samp:`{COARRAY}`. If :samp:`{DIM}` is present, the result is a scalar + corresponding to the lower cobound of the array along that codimension. + + Standard: + Fortran 2008 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = LCOBOUND(COARRAY [, DIM [, KIND]]) + + See also: + :ref:`UCOBOUND`, + :ref:`LBOUND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/leadz.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/leadz.rst new file mode 100644 index 0000000..327cf89 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/leadz.rst @@ -0,0 +1,47 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _leadz: + +LEADZ --- Number of leading zero bits of an integer +*************************************************** + +.. index:: LEADZ, zero bits + +.. function:: LEADZ(I) + + ``LEADZ`` returns the number of leading zero bits of an integer. + + :param I: + Shall be of type ``INTEGER``. + + :return: + The type of the return value is the default ``INTEGER``. + If all the bits of ``I`` are zero, the result value is ``BIT_SIZE(I)``. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LEADZ(I) + + Example: + .. code-block:: fortran + + PROGRAM test_leadz + WRITE (*,*) BIT_SIZE(1) ! prints 32 + WRITE (*,*) LEADZ(1) ! prints 31 + END PROGRAM + + See also: + :ref:`BIT_SIZE`, + :ref:`TRAILZ`, + :ref:`POPCNT`, + :ref:`POPPAR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/len.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/len.rst new file mode 100644 index 0000000..433659c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/len.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _len: + +.. index:: LEN + +.. index:: string, length + +LEN --- Length of a character entity +************************************ + +.. function:: LEN(STRING , KIND) + + Returns the length of a character string. If :samp:`{STRING}` is an array, + the length of an element of :samp:`{STRING}` is returned. Note that + :samp:`{STRING}` need not be defined when this intrinsic is invoked, since + only the length, not the content, of :samp:`{STRING}` is needed. + + :param STRING: + Shall be a scalar or array of type + ``CHARACTER``, with ``INTENT(IN)`` + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + + Standard: + Fortran 77 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + L = LEN(STRING [, KIND]) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``LEN(STRING)`` + - ``CHARACTER`` + - ``INTEGER`` + - Fortran 77 and later + + See also: + :ref:`LEN_TRIM`, + :ref:`ADJUSTL`, + :ref:`ADJUSTR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/lentrim.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/lentrim.rst new file mode 100644 index 0000000..51c8e3a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/lentrim.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: LEN_TRIM, string, length, without trailing whitespace + +.. _len_trim: + +LEN_TRIM --- Length of a character entity without trailing blank characters +*************************************************************************** + +.. function:: LEN_TRIM(STRING , KIND) + + Returns the length of a character string, ignoring any trailing blanks. + + :param STRING: + Shall be a scalar of type ``CHARACTER``, + with ``INTENT(IN)`` + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + + Standard: + Fortran 90 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LEN_TRIM(STRING [, KIND]) + + See also: + :ref:`LEN`, + :ref:`ADJUSTL`, + :ref:`ADJUSTR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/lge.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/lge.rst new file mode 100644 index 0000000..f56ae88 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/lge.rst @@ -0,0 +1,63 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _lge: + +.. index:: LGE + +.. index:: lexical comparison of strings + +.. index:: string, comparison + +LGE --- Lexical greater than or equal +************************************* + +.. function:: LGE(STRING_A, STRING_B) + + 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. + + :param STRING_A: + Shall be of default ``CHARACTER`` type. + + :param STRING_B: + Shall be of default ``CHARACTER`` type. + + :return: + Returns ``.TRUE.`` if ``STRING_A >= STRING_B``, and ``.FALSE.`` + otherwise, based on the ASCII ordering. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LGE(STRING_A, STRING_B) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``LGE(STRING_A,STRING_B)`` + - ``CHARACTER`` + - ``LOGICAL`` + - Fortran 77 and later + + See also: + :ref:`LGT`, + :ref:`LLE`, + :ref:`LLT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/lgt.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/lgt.rst new file mode 100644 index 0000000..06d70c7 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/lgt.rst @@ -0,0 +1,63 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _lgt: + +.. index:: LGT + +.. index:: lexical comparison of strings + +.. index:: string, comparison + +LGT --- Lexical greater than +**************************** + +.. function:: LGT(STRING_A, STRING_B) + + 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. + + :param STRING_A: + Shall be of default ``CHARACTER`` type. + + :param STRING_B: + Shall be of default ``CHARACTER`` type. + + :return: + Returns ``.TRUE.`` if ``STRING_A > STRING_B``, and ``.FALSE.`` + otherwise, based on the ASCII ordering. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LGT(STRING_A, STRING_B) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``LGT(STRING_A,STRING_B)`` + - ``CHARACTER`` + - ``LOGICAL`` + - Fortran 77 and later + + See also: + :ref:`LGE`, + :ref:`LLE`, + :ref:`LLT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/link.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/link.rst new file mode 100644 index 0000000..e24cf2e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/link.rst @@ -0,0 +1,45 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: LINK, file system, create link, file system, hard link + +.. _link: + +LINK --- Create a hard link +*************************** + +.. function:: LINK(PATH1, PATH2) + + Makes a (hard) link from file :samp:`{PATH1}` to :samp:`{PATH2}`. A null + character (``CHAR(0)``) can be used to mark the end of the names in + :samp:`{PATH1}` and :samp:`{PATH2}` ; otherwise, trailing blanks in the file + names are ignored. If the :samp:`{STATUS}` argument is supplied, it + contains 0 on success or a nonzero error code upon return; see + ``link(2)``. + + :param PATH1: + Shall be of default ``CHARACTER`` type. + + :param PATH2: + Shall be of default ``CHARACTER`` type. + + :param STATUS: + (Optional) Shall be of default ``INTEGER`` type. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL LINK(PATH1, PATH2 [, STATUS]) + STATUS = LINK(PATH1, PATH2) + + See also: + :ref:`SYMLNK`, + :ref:`UNLINK`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/lle.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/lle.rst new file mode 100644 index 0000000..f256bcc --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/lle.rst @@ -0,0 +1,63 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _lle: + +.. index:: LLE + +.. index:: lexical comparison of strings + +.. index:: string, comparison + +LLE --- Lexical less than or equal +********************************** + +.. function:: LLE(STRING_A, STRING_B) + + 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. + + :param STRING_A: + Shall be of default ``CHARACTER`` type. + + :param STRING_B: + Shall be of default ``CHARACTER`` type. + + :return: + Returns ``.TRUE.`` if ``STRING_A <= STRING_B``, and ``.FALSE.`` + otherwise, based on the ASCII ordering. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LLE(STRING_A, STRING_B) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``LLE(STRING_A,STRING_B)`` + - ``CHARACTER`` + - ``LOGICAL`` + - Fortran 77 and later + + See also: + :ref:`LGE`, + :ref:`LGT`, + :ref:`LLT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/llt.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/llt.rst new file mode 100644 index 0000000..b7f1851 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/llt.rst @@ -0,0 +1,63 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _llt: + +.. index:: LLT + +.. index:: lexical comparison of strings + +.. index:: string, comparison + +LLT --- Lexical less than +************************* + +.. function:: LLT(STRING_A, STRING_B) + + 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. + + :param STRING_A: + Shall be of default ``CHARACTER`` type. + + :param STRING_B: + Shall be of default ``CHARACTER`` type. + + :return: + Returns ``.TRUE.`` if ``STRING_A < STRING_B``, and ``.FALSE.`` + otherwise, based on the ASCII ordering. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LLT(STRING_A, STRING_B) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``LLT(STRING_A,STRING_B)`` + - ``CHARACTER`` + - ``LOGICAL`` + - Fortran 77 and later + + See also: + :ref:`LGE`, + :ref:`LGT`, + :ref:`LLE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/lnblnk.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/lnblnk.rst new file mode 100644 index 0000000..aff6838 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/lnblnk.rst @@ -0,0 +1,39 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: LNBLNK, string, find non-blank character + +.. _lnblnk: + +LNBLNK --- Index of the last non-blank character in a string +************************************************************ + +.. function:: LNBLNK(STRING) + + Returns the length of a character string, ignoring any trailing blanks. + This is identical to the standard ``LEN_TRIM`` intrinsic, and is only + included for backwards compatibility. + + :param STRING: + Shall be a scalar of type ``CHARACTER``, + with ``INTENT(IN)`` + + :return: + The return value is of ``INTEGER(kind=4)`` type. + + Standard: + GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LNBLNK(STRING) + + See also: + :ref:`index-intrinsic`, + :ref:`LEN_TRIM`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/loc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/loc.rst new file mode 100644 index 0000000..f503a01 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/loc.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: LOC, location of a variable in memory + +.. _loc: + +LOC --- Returns the address of a variable +***************************************** + +.. function:: LOC(X) + + ``LOC(X)`` returns the address of :samp:`{X}` as an integer. + + :param X: + Variable of any type. + + :return: + The return value is of type ``INTEGER``, with a ``KIND`` + corresponding to the size (in bytes) of a memory address on the target + machine. + + Standard: + GNU extension + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = LOC(X) + + Example: + .. code-block:: fortran + + program test_loc + integer :: i + real :: r + i = loc(r) + print *, i + end program test_loc
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/log.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/log.rst new file mode 100644 index 0000000..dd960ba --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/log.rst @@ -0,0 +1,93 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _log: + +.. index:: LOG + +.. index:: ALOG + +.. index:: DLOG + +.. index:: CLOG + +.. index:: ZLOG + +.. index:: CDLOG + +.. index:: exponential function, inverse + +.. index:: logarithm function + +.. index:: natural logarithm function + +LOG --- Natural logarithm function +********************************** + +.. function:: LOG(X) + + ``LOG(X)`` computes the natural logarithm of :samp:`{X}`, i.e. the + logarithm to the base e. + + :param X: + The type shall be ``REAL`` or + ``COMPLEX``. + + :return: + The return value is of type ``REAL`` or ``COMPLEX``. + The kind type parameter is the same as :samp:`{X}`. + If :samp:`{X}` is ``COMPLEX``, the imaginary part \omega is in the range + -\pi < \omega \leq \pi. + + Standard: + Fortran 77 and later, has GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LOG(X) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ALOG(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 or later + * - ``DLOG(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 or later + * - ``CLOG(X)`` + - ``COMPLEX(4) X`` + - ``COMPLEX(4)`` + - Fortran 77 or later + * - ``ZLOG(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + * - ``CDLOG(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/log10.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/log10.rst new file mode 100644 index 0000000..7529706 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/log10.rst @@ -0,0 +1,69 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _log10: + +.. index:: LOG10 + +.. index:: ALOG10 + +.. index:: DLOG10 + +.. index:: exponential function, inverse + +.. index:: logarithm function with base 10 + +.. index:: base 10 logarithm function + +LOG10 --- Base 10 logarithm function +************************************ + +.. function:: LOG10(X) + + ``LOG10(X)`` computes the base 10 logarithm of :samp:`{X}`. + + :param X: + The type shall be ``REAL``. + + :return: + The return value is of type ``REAL`` or ``COMPLEX``. + The kind type parameter is the same as :samp:`{X}`. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LOG10(X) + + Example: + .. code-block:: fortran + + program test_log10 + real(8) :: x = 10.0_8 + x = log10(x) + end program test_log10 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``ALOG10(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DLOG10(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/loggamma.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/loggamma.rst new file mode 100644 index 0000000..e9952bd --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/loggamma.rst @@ -0,0 +1,76 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _log_gamma: + +.. index:: LOG_GAMMA + +.. index:: LGAMMA + +.. index:: ALGAMA + +.. index:: DLGAMA + +.. index:: Gamma function, logarithm of + +LOG_GAMMA --- Logarithm of the Gamma function +********************************************* + +.. function:: LOG_GAMMA(X) + + ``LOG_GAMMA(X)`` computes the natural logarithm of the absolute value + of the Gamma (\Gamma) function. + + :param X: + Shall be of type ``REAL`` and neither zero + nor a negative integer. + + :return: + The return value is of type ``REAL`` of the same kind as :samp:`{X}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + X = LOG_GAMMA(X) + + Example: + .. code-block:: fortran + + program test_log_gamma + real :: x = 1.0 + x = lgamma(x) ! returns 0.0 + end program test_log_gamma + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``LGAMMA(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - GNU extension + * - ``ALGAMA(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - GNU extension + * - ``DLGAMA(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + + See also: + Gamma function: + :ref:`GAMMA`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/logical.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/logical.rst new file mode 100644 index 0000000..fe3706f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/logical.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _logical: + +LOGICAL --- Convert to logical type +*********************************** + +.. index:: LOGICAL, conversion, to logical + +.. function:: LOGICAL(L, KIND) + + Converts one kind of ``LOGICAL`` variable to another. + + :param L: + The type shall be ``LOGICAL``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is a ``LOGICAL`` value equal to :samp:`{L}`, with a + kind corresponding to :samp:`{KIND}`, or of the default logical kind if + :samp:`{KIND}` is not given. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LOGICAL(L [, KIND]) + + See also: + :ref:`INT`, + :ref:`REAL`, + :ref:`CMPLX`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/lshift.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/lshift.rst new file mode 100644 index 0000000..031e3e1 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/lshift.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _lshift: + +LSHIFT --- Left shift bits +************************** + +.. index:: LSHIFT, bits, shift left + +.. function:: LSHIFT(I, SHIFT) + + ``LSHIFT`` returns a value corresponding to :samp:`{I}` with all of the + bits shifted left by :samp:`{SHIFT}` places. :samp:`{SHIFT}` shall be + nonnegative and less than or equal to ``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. + + :param I: + The type shall be ``INTEGER``. + + :param SHIFT: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the same kind as + :samp:`{I}`. + + Standard: + GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = LSHIFT(I, SHIFT) + + See also: + :ref:`ISHFT`, + :ref:`ISHFTC`, + :ref:`RSHIFT`, + :ref:`SHIFTA`, + :ref:`SHIFTL`, + :ref:`SHIFTR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/lstat.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/lstat.rst new file mode 100644 index 0000000..0abd89d --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/lstat.rst @@ -0,0 +1,49 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _lstat: + +LSTAT --- Get file status +************************* + +.. index:: LSTAT, file system, file status + +.. function:: LSTAT(NAME, VALUES, STATUS) + + ``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. + + :param NAME: + The type shall be ``CHARACTER`` of the default + kind, a valid path within the file system. + + :param VALUES: + The type shall be ``INTEGER(4), DIMENSION(13)``. + + :param STATUS: + (Optional) status flag of type ``INTEGER(4)``. + Returns 0 on success and a system specific error code otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL LSTAT(NAME, VALUES [, STATUS]) + STATUS = LSTAT(NAME, VALUES) + + Example: + See :ref:`STAT` for an example. + + See also: + To stat an open file: + :ref:`FSTAT` + To stat a file: + :ref:`STAT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ltime.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ltime.rst new file mode 100644 index 0000000..d09728e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ltime.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: LTIME, time, conversion to local time info + +.. _ltime: + +LTIME --- Convert time to local time info +***************************************** + +.. function:: LTIME(TIME, VALUES) + + Given a system time value :samp:`{TIME}` (as provided by the :ref:`TIME` + intrinsic), fills :samp:`{VALUES}` with values extracted from it appropriate + to the local time zone using ``localtime(3)``. + + :param TIME: + An ``INTEGER`` scalar expression + corresponding to a system time, with ``INTENT(IN)``. + + :param VALUES: + A default ``INTEGER`` array with 9 elements, + with ``INTENT(OUT)``. + + :return: + The elements of :samp:`{VALUES}` are assigned as follows: + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL LTIME(TIME, VALUES) + + See also: + :ref:`DATE_AND_TIME`, + :ref:`CTIME`, + :ref:`GMTIME`, + :ref:`TIME`, + :ref:`TIME8`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/malloc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/malloc.rst new file mode 100644 index 0000000..581ae06 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/malloc.rst @@ -0,0 +1,66 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MALLOC, pointer, cray + +.. _malloc: + +MALLOC --- Allocate dynamic memory +********************************** + +.. function:: MALLOC(SIZE) + + ``MALLOC(SIZE)`` allocates :samp:`{SIZE}` bytes of dynamic memory and + returns the address of the allocated memory. The ``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 + ``ALLOCATE``. + + :param SIZE: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER(K)``, with :samp:`{K}` such that + variables of type ``INTEGER(K)`` have the same size as + C pointers (``sizeof(void *)``). + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + PTR = MALLOC(SIZE) + + Example: + The following example demonstrates the use of ``MALLOC`` and + ``FREE`` with Cray pointers. + + .. code-block:: fortran + + 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 + + See also: + :ref:`FREE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/maskl.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/maskl.rst new file mode 100644 index 0000000..0d0ea90 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/maskl.rst @@ -0,0 +1,42 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _maskl: + +MASKL --- Left justified mask +***************************** + +.. index:: MASKL, mask, left justified + +.. function:: MASKL(I, KIND) + + ``MASKL(I[, KIND])`` has its leftmost :samp:`{I}` bits set to 1, and the + remaining bits set to 0. + + :param I: + Shall be of type ``INTEGER``. + + :param KIND: + Shall be a scalar constant expression of type + ``INTEGER``. + + :return: + The return value is of type ``INTEGER``. If :samp:`{KIND}` is present, it + specifies the kind value of the return type; otherwise, it is of the + default integer kind. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = MASKL(I[, KIND]) + + See also: + :ref:`MASKR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/maskr.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/maskr.rst new file mode 100644 index 0000000..30f4e37 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/maskr.rst @@ -0,0 +1,42 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MASKR, mask, right justified + +.. _maskr: + +MASKR --- Right justified mask +****************************** + +.. function:: MASKR(I, KIND) + + ``MASKL(I[, KIND])`` has its rightmost :samp:`{I}` bits set to 1, and the + remaining bits set to 0. + + :param I: + Shall be of type ``INTEGER``. + + :param KIND: + Shall be a scalar constant expression of type + ``INTEGER``. + + :return: + The return value is of type ``INTEGER``. If :samp:`{KIND}` is present, it + specifies the kind value of the return type; otherwise, it is of the + default integer kind. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = MASKR(I[, KIND]) + + See also: + :ref:`MASKL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/matmul.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/matmul.rst new file mode 100644 index 0000000..8188492 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/matmul.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MATMUL, matrix multiplication, product, matrix + +.. _matmul: + +MATMUL --- matrix multiplication +******************************** + +.. function:: MATMUL(MATRIX_A, MATRIX_B) + + Performs a matrix multiplication on numeric or logical arguments. + + :param MATRIX_A: + An array of ``INTEGER``, + ``REAL``, ``COMPLEX``, or ``LOGICAL`` type, with a rank of + one or two. + + :param MATRIX_B: + An array of ``INTEGER``, + ``REAL``, or ``COMPLEX`` type if :samp:`{MATRIX_A}` is of a numeric + type; otherwise, an array of ``LOGICAL`` type. The rank shall be one + or two, and the first (or only) dimension of :samp:`{MATRIX_B}` shall be + equal to the last (or only) dimension of :samp:`{MATRIX_A}`. + :samp:`{MATRIX_A}` and :samp:`{MATRIX_B}` shall not both be rank one arrays. + + :return: + The matrix product of :samp:`{MATRIX_A}` and :samp:`{MATRIX_B}`. The type and + kind of the result follow the usual type and kind promotion rules, as + for the ``*`` or ``.AND.`` operators. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = MATMUL(MATRIX_A, MATRIX_B)
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/max.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/max.rst new file mode 100644 index 0000000..7c6179a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/max.rst @@ -0,0 +1,86 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _max: + +.. index:: MAX + +.. index:: MAX0 + +.. index:: AMAX0 + +.. index:: MAX1 + +.. index:: AMAX1 + +.. index:: DMAX1 + +.. index:: maximum value + +MAX --- Maximum value of an argument list +***************************************** + +.. function:: MAX(A1, A2 , A3 , ...) + + Returns the argument with the largest (most positive) value. + + :param A1: + The type shall be ``INTEGER`` or + ``REAL``. + + :param A2}, {A3}, ...: + An expression of the same type and kind + as :samp:`{A1}`. (As a GNU extension, arguments of different kinds are + permitted.) + + :return: + The return value corresponds to the maximum value among the arguments, + and has the same type and kind as the first argument. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = MAX(A1, A2 [, A3 [, ...]]) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``MAX0(A1)`` + - ``INTEGER(4) A1`` + - ``INTEGER(4)`` + - Fortran 77 and later + * - ``AMAX0(A1)`` + - ``INTEGER(4) A1`` + - ``REAL(MAX(X))`` + - Fortran 77 and later + * - ``MAX1(A1)`` + - ``REAL A1`` + - ``INT(MAX(X))`` + - Fortran 77 and later + * - ``AMAX1(A1)`` + - ``REAL(4) A1`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DMAX1(A1)`` + - ``REAL(8) A1`` + - ``REAL(8)`` + - Fortran 77 and later + + See also: + :ref:`MAXLOC` + :ref:`MAXVAL`, + :ref:`MIN`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/maxexponent.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/maxexponent.rst new file mode 100644 index 0000000..8d42d60 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/maxexponent.rst @@ -0,0 +1,45 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MAXEXPONENT, model representation, maximum exponent + +.. _maxexponent: + +MAXEXPONENT --- Maximum exponent of a real kind +*********************************************** + +.. function:: MAXEXPONENT(X) + + ``MAXEXPONENT(X)`` returns the maximum exponent in the model of the + type of ``X``. + + :param X: + Shall be of type ``REAL``. + + :return: + The return value is of type ``INTEGER`` and of the default integer + kind. + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = MAXEXPONENT(X) + + Example: + .. code-block:: fortran + + program exponents + real(kind=4) :: x + real(kind=8) :: y + + print *, minexponent(x), maxexponent(x) + print *, minexponent(y), maxexponent(y) + end program exponents
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/maxloc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/maxloc.rst new file mode 100644 index 0000000..2e3d2ad --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/maxloc.rst @@ -0,0 +1,76 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MAXLOC, array, location of maximum element + +.. _maxloc: + +MAXLOC --- Location of the maximum value within an array +******************************************************** + +.. function:: MAXLOC(ARRAY , MASK ,KIND ,BACK) + + Determines the location of the element in the array with the maximum + value, or, if the :samp:`{DIM}` argument is supplied, determines the + locations of the maximum element along each row of the array in the + :samp:`{DIM}` direction. If :samp:`{MASK}` is present, only the elements for + which :samp:`{MASK}` is ``.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 + :samp:`{BACK}` is not present, or is false; if :samp:`{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 :samp:`{MASK}` are ``.FALSE.``, then + the result is an array of zeroes. Similarly, if :samp:`{DIM}` is supplied + and all of the elements of :samp:`{MASK}` along a given row are zero, the + result value for that row is zero. + + :param ARRAY: + Shall be an array of type ``INTEGER`` or + ``REAL``. + + :param DIM: + (Optional) Shall be a scalar of type + ``INTEGER``, with a value between one and the rank of :samp:`{ARRAY}`, + inclusive. It may not be an optional dummy argument. + + :param MASK: + Shall be of type ``LOGICAL``, + and conformable with :samp:`{ARRAY}`. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :param BACK: + (Optional) A scalar of type ``LOGICAL``. + + :return: + If :samp:`{DIM}` is absent, the result is a rank-one array with a length + equal to the rank of :samp:`{ARRAY}`. If :samp:`{DIM}` is present, the result + is an array with a rank one less than the rank of :samp:`{ARRAY}`, and a + size corresponding to the size of :samp:`{ARRAY}` with the :samp:`{DIM}` + dimension removed. If :samp:`{DIM}` is present and :samp:`{ARRAY}` has a rank + of one, the result is a scalar. If the optional argument :samp:`{KIND}` + is present, the result is an integer of kind :samp:`{KIND}`, otherwise it + is of default kind. + + Standard: + Fortran 95 and later; :samp:`{ARRAY}` of ``CHARACTER`` and the + :samp:`{KIND}` argument are available in Fortran 2003 and later. + The :samp:`{BACK}` argument is available in Fortran 2008 and later. + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK]) + RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK]) + + See also: + :ref:`FINDLOC`, + :ref:`MAX`, + :ref:`MAXVAL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/maxval.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/maxval.rst new file mode 100644 index 0000000..9b3dcc5 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/maxval.rst @@ -0,0 +1,58 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MAXVAL, array, maximum value, maximum value + +.. _maxval: + +MAXVAL --- Maximum value of an array +************************************ + +.. function:: MAXVAL(ARRAY , MASK) + + Determines the maximum value of the elements in an array value, or, if + the :samp:`{DIM}` argument is supplied, determines the maximum value along + each row of the array in the :samp:`{DIM}` direction. If :samp:`{MASK}` is + present, only the elements for which :samp:`{MASK}` is ``.TRUE.`` are + considered. If the array has zero size, or all of the elements of + :samp:`{MASK}` are ``.FALSE.``, then the result is ``-HUGE(ARRAY)`` + if :samp:`{ARRAY}` is numeric, or a string of nulls if :samp:`{ARRAY}` is of character + type. + + :param ARRAY: + Shall be an array of type ``INTEGER`` or + ``REAL``. + + :param DIM: + (Optional) Shall be a scalar of type + ``INTEGER``, with a value between one and the rank of :samp:`{ARRAY}`, + inclusive. It may not be an optional dummy argument. + + :param MASK: + (Optional) Shall be of type ``LOGICAL``, + and conformable with :samp:`{ARRAY}`. + + :return: + If :samp:`{DIM}` is absent, or if :samp:`{ARRAY}` has a rank of one, the result + is a scalar. If :samp:`{DIM}` is present, the result is an array with a + rank one less than the rank of :samp:`{ARRAY}`, and a size corresponding to + the size of :samp:`{ARRAY}` with the :samp:`{DIM}` dimension removed. In all + cases, the result is of the same type and kind as :samp:`{ARRAY}`. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = MAXVAL(ARRAY, DIM [, MASK]) + RESULT = MAXVAL(ARRAY [, MASK]) + + See also: + :ref:`MAX`, + :ref:`MAXLOC`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/mclock.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/mclock.rst new file mode 100644 index 0000000..3ac35fb --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/mclock.rst @@ -0,0 +1,39 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MCLOCK, time, clock ticks, clock ticks + +.. _mclock: + +MCLOCK --- Time function +************************ + +.. function:: MCLOCK() + + Returns the number of clock ticks since the start of the process, based + on the function ``clock(3)`` in the C standard library. + + :return: + The return value is a scalar of type ``INTEGER(4)``, equal to the + number of clock ticks since the start of the process, or ``-1`` if + the system does not support ``clock(3)``. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = MCLOCK() + + See also: + :ref:`CTIME`, + :ref:`GMTIME`, + :ref:`LTIME`, + :ref:`MCLOCK`, + :ref:`TIME`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/mclock8.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/mclock8.rst new file mode 100644 index 0000000..3524e52 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/mclock8.rst @@ -0,0 +1,39 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MCLOCK8, time, clock ticks, clock ticks + +.. _mclock8: + +MCLOCK8 --- Time function (64-bit) +********************************** + +.. function:: MCLOCK8() + + Returns the number of clock ticks since the start of the process, based + on the function ``clock(3)`` in the C standard library. + + :return: + The return value is a scalar of type ``INTEGER(8)``, equal to the + number of clock ticks since the start of the process, or ``-1`` if + the system does not support ``clock(3)``. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = MCLOCK8() + + See also: + :ref:`CTIME`, + :ref:`GMTIME`, + :ref:`LTIME`, + :ref:`MCLOCK`, + :ref:`TIME8`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/merge.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/merge.rst new file mode 100644 index 0000000..556358a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/merge.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MERGE, array, merge arrays, array, combine arrays + +.. _merge: + +MERGE --- Merge variables +************************* + +.. function:: MERGE(TSOURCE, FSOURCE, MASK) + + Select values from two arrays according to a logical mask. The result + is equal to :samp:`{TSOURCE}` if :samp:`{MASK}` is ``.TRUE.``, or equal to + :samp:`{FSOURCE}` if it is ``.FALSE.``. + + :param TSOURCE: + May be of any type. + + :param FSOURCE: + Shall be of the same type and type parameters + as :samp:`{TSOURCE}`. + + :param MASK: + Shall be of type ``LOGICAL``. + + :return: + The result is of the same type and type parameters as :samp:`{TSOURCE}`. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = MERGE(TSOURCE, FSOURCE, MASK)
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/mergebits.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/mergebits.rst new file mode 100644 index 0000000..80dd38b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/mergebits.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MERGE_BITS, bits, merge + +.. _merge_bits: + +MERGE_BITS --- Merge of bits under mask +*************************************** + +.. function:: MERGE_BITS(I, J, MASK) + + ``MERGE_BITS(I, J, MASK)`` merges the bits of :samp:`{I}` and :samp:`{J}` + as determined by the mask. The i-th bit of the result is equal to the + i-th bit of :samp:`{I}` if the i-th bit of :samp:`{MASK}` is 1; it is equal to + the i-th bit of :samp:`{J}` otherwise. + + :param I: + Shall be of type ``INTEGER`` or a boz-literal-constant. + + :param J: + Shall be of type ``INTEGER`` with the same + kind type parameter as :samp:`{I}` or a boz-literal-constant. + :samp:`{I}` and :samp:`{J}` shall not both be boz-literal-constants. + + :param MASK: + Shall be of type ``INTEGER`` or a boz-literal-constant + and of the same kind as :samp:`{I}`. + + :return: + The result is of the same type and kind as :samp:`{I}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = MERGE_BITS(I, J, MASK)
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/min.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/min.rst new file mode 100644 index 0000000..aefd814 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/min.rst @@ -0,0 +1,86 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _min: + +.. index:: MIN + +.. index:: MIN0 + +.. index:: AMIN0 + +.. index:: MIN1 + +.. index:: AMIN1 + +.. index:: DMIN1 + +.. index:: minimum value + +MIN --- Minimum value of an argument list +***************************************** + +.. function:: MIN(A1, A2 , A3, ...) + + Returns the argument with the smallest (most negative) value. + + :param A1: + The type shall be ``INTEGER`` or + ``REAL``. + + :param A2}, {A3}, ...: + An expression of the same type and kind + as :samp:`{A1}`. (As a GNU extension, arguments of different kinds are + permitted.) + + :return: + The return value corresponds to the minimum value among the arguments, + and has the same type and kind as the first argument. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = MIN(A1, A2 [, A3, ...]) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``MIN0(A1)`` + - ``INTEGER(4) A1`` + - ``INTEGER(4)`` + - Fortran 77 and later + * - ``AMIN0(A1)`` + - ``INTEGER(4) A1`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``MIN1(A1)`` + - ``REAL A1`` + - ``INTEGER(4)`` + - Fortran 77 and later + * - ``AMIN1(A1)`` + - ``REAL(4) A1`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DMIN1(A1)`` + - ``REAL(8) A1`` + - ``REAL(8)`` + - Fortran 77 and later + + See also: + :ref:`MAX`, + :ref:`MINLOC`, + :ref:`MINVAL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/minexponent.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/minexponent.rst new file mode 100644 index 0000000..546a46b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/minexponent.rst @@ -0,0 +1,37 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MINEXPONENT, model representation, minimum exponent + +.. _minexponent: + +MINEXPONENT --- Minimum exponent of a real kind +*********************************************** + +.. function:: MINEXPONENT(X) + + ``MINEXPONENT(X)`` returns the minimum exponent in the model of the + type of ``X``. + + :param X: + Shall be of type ``REAL``. + + :return: + The return value is of type ``INTEGER`` and of the default integer + kind. + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = MINEXPONENT(X) + + Example: + See ``MAXEXPONENT`` for an example.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/minloc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/minloc.rst new file mode 100644 index 0000000..49496be --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/minloc.rst @@ -0,0 +1,76 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _minloc: + +MINLOC --- Location of the minimum value within an array +******************************************************** + +.. index:: MINLOC, array, location of minimum element + +.. function:: MINLOC(ARRAY, MASK, KIND, BACK) + + Determines the location of the element in the array with the minimum + value, or, if the :samp:`{DIM}` argument is supplied, determines the + locations of the minimum element along each row of the array in the + :samp:`{DIM}` direction. If :samp:`{MASK}` is present, only the elements for + which :samp:`{MASK}` is ``.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 + :samp:`{BACK}` is not present, or is false; if :samp:`{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 :samp:`{MASK}` are ``.FALSE.``, then + the result is an array of zeroes. Similarly, if :samp:`{DIM}` is supplied + and all of the elements of :samp:`{MASK}` along a given row are zero, the + result value for that row is zero. + + :param ARRAY: + Shall be an array of type ``INTEGER``, + ``REAL`` or ``CHARACTER``. + + :param DIM: + (Optional) Shall be a scalar of type + ``INTEGER``, with a value between one and the rank of :samp:`{ARRAY}`, + inclusive. It may not be an optional dummy argument. + + :param MASK: + Shall be of type ``LOGICAL``, + and conformable with :samp:`{ARRAY}`. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :param BACK: + (Optional) A scalar of type ``LOGICAL``. + + :return: + If :samp:`{DIM}` is absent, the result is a rank-one array with a length + equal to the rank of :samp:`{ARRAY}`. If :samp:`{DIM}` is present, the result + is an array with a rank one less than the rank of :samp:`{ARRAY}`, and a + size corresponding to the size of :samp:`{ARRAY}` with the :samp:`{DIM}` + dimension removed. If :samp:`{DIM}` is present and :samp:`{ARRAY}` has a rank + of one, the result is a scalar. If the optional argument :samp:`{KIND}` + is present, the result is an integer of kind :samp:`{KIND}`, otherwise it + is of default kind. + + Standard: + Fortran 90 and later; :samp:`{ARRAY}` of ``CHARACTER`` and the + :samp:`{KIND}` argument are available in Fortran 2003 and later. + The :samp:`{BACK}` argument is available in Fortran 2008 and later. + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK]) + RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK]) + + See also: + :ref:`FINDLOC`, + :ref:`MIN`, + :ref:`MINVAL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/minval.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/minval.rst new file mode 100644 index 0000000..55fd75d --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/minval.rst @@ -0,0 +1,58 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MINVAL, array, minimum value, minimum value + +.. _minval: + +MINVAL --- Minimum value of an array +************************************ + +.. function:: MINVAL(ARRAY , MASK) + + Determines the minimum value of the elements in an array value, or, if + the :samp:`{DIM}` argument is supplied, determines the minimum value along + each row of the array in the :samp:`{DIM}` direction. If :samp:`{MASK}` is + present, only the elements for which :samp:`{MASK}` is ``.TRUE.`` are + considered. If the array has zero size, or all of the elements of + :samp:`{MASK}` are ``.FALSE.``, then the result is ``HUGE(ARRAY)`` if + :samp:`{ARRAY}` is numeric, or a string of ``CHAR(255)`` characters if + :samp:`{ARRAY}` is of character type. + + :param ARRAY: + Shall be an array of type ``INTEGER`` or + ``REAL``. + + :param DIM: + (Optional) Shall be a scalar of type + ``INTEGER``, with a value between one and the rank of :samp:`{ARRAY}`, + inclusive. It may not be an optional dummy argument. + + :param MASK: + Shall be of type ``LOGICAL``, + and conformable with :samp:`{ARRAY}`. + + :return: + If :samp:`{DIM}` is absent, or if :samp:`{ARRAY}` has a rank of one, the result + is a scalar. If :samp:`{DIM}` is present, the result is an array with a + rank one less than the rank of :samp:`{ARRAY}`, and a size corresponding to + the size of :samp:`{ARRAY}` with the :samp:`{DIM}` dimension removed. In all + cases, the result is of the same type and kind as :samp:`{ARRAY}`. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = MINVAL(ARRAY, DIM [, MASK]) + RESULT = MINVAL(ARRAY [, MASK]) + + See also: + :ref:`MIN`, + :ref:`MINLOC`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/mod.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/mod.rst new file mode 100644 index 0000000..35624ae --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/mod.rst @@ -0,0 +1,118 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _mod: + +.. index:: MOD + +.. index:: AMOD + +.. index:: DMOD + +.. index:: BMOD + +.. index:: IMOD + +.. index:: JMOD + +.. index:: KMOD + +.. index:: remainder + +.. index:: division, remainder + +MOD --- Remainder function +************************** + +.. function:: MOD(A,P) + + ``MOD(A,P)`` computes the remainder of the division of A by P. + + :param A: + Shall be a scalar of type ``INTEGER`` or ``REAL``. + + :param P: + Shall be a scalar of the same type and kind as :samp:`{A}` + and not equal to zero. (As a GNU extension, arguments of different kinds are + permitted.) + + :return: + The return value is the result of ``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.) + + Standard: + Fortran 77 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = MOD(A, P) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Arguments + - Return type + - Standard + + * - ``MOD(A,P)`` + - ``INTEGER A,P`` + - ``INTEGER`` + - Fortran 77 and later + * - ``AMOD(A,P)`` + - ``REAL(4) A,P`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DMOD(A,P)`` + - ``REAL(8) A,P`` + - ``REAL(8)`` + - Fortran 77 and later + * - ``BMOD(A,P)`` + - ``INTEGER(1) A,P`` + - ``INTEGER(1)`` + - GNU extension + * - ``IMOD(A,P)`` + - ``INTEGER(2) A,P`` + - ``INTEGER(2)`` + - GNU extension + * - ``JMOD(A,P)`` + - ``INTEGER(4) A,P`` + - ``INTEGER(4)`` + - GNU extension + * - ``KMOD(A,P)`` + - ``INTEGER(8) A,P`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`MODULO`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/modulo.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/modulo.rst new file mode 100644 index 0000000..82e2126 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/modulo.rst @@ -0,0 +1,55 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MODULO, modulo, division, modulo + +.. _modulo: + +MODULO --- Modulo function +************************** + +.. function:: MODULO(A,P) + + ``MODULO(A,P)`` computes the :samp:`{A}` modulo :samp:`{P}`. + + :param A: + Shall be a scalar of type ``INTEGER`` or ``REAL``. + + :param P: + Shall be a scalar of the same type and kind as :samp:`{A}`. + It shall not be zero. (As a GNU extension, arguments of different kinds are + permitted.) + + :return: + 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.) + + Standard: + Fortran 95 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = MODULO(A, P) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`MOD`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/movealloc.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/movealloc.rst new file mode 100644 index 0000000..8c39ad8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/movealloc.rst @@ -0,0 +1,51 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: MOVE_ALLOC, moving allocation, allocation, moving + +.. _move_alloc: + +MOVE_ALLOC --- Move allocation from one object to another +********************************************************* + +.. function:: MOVE_ALLOC(FROM, TO) + + ``MOVE_ALLOC(FROM, TO)`` moves the allocation from :samp:`{FROM}` to + :samp:`{TO}`. :samp:`{FROM}` will become deallocated in the process. + + :param FROM: + ``ALLOCATABLE``, ``INTENT(INOUT)``, may be + of any type and kind. + + :param TO: + ``ALLOCATABLE``, ``INTENT(OUT)``, shall be + of the same type, kind and rank as :samp:`{FROM}`. + + :return: + None + + Standard: + Fortran 2003 and later + + Class: + Pure subroutine + + Syntax: + .. code-block:: fortran + + CALL MOVE_ALLOC(FROM, TO) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/mvbits.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/mvbits.rst new file mode 100644 index 0000000..a3b0121 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/mvbits.rst @@ -0,0 +1,95 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _mvbits: + +.. index:: MVBITS + +.. index:: BMVBITS + +.. index:: IMVBITS + +.. index:: JMVBITS + +.. index:: KMVBITS + +.. index:: bits, move + +MVBITS --- Move bits from one integer to another +************************************************ + +.. function:: MVBITS(FROM, FROMPOS, LEN, TO, TOPOS) + + Moves :samp:`{LEN}` bits from positions :samp:`{FROMPOS}` through + ``FROMPOS+LEN-1`` of :samp:`{FROM}` to positions :samp:`{TOPOS}` through + ``TOPOS+LEN-1`` of :samp:`{TO}`. The portion of argument :samp:`{TO}` not + affected by the movement of bits is unchanged. The values of + ``FROMPOS+LEN-1`` and ``TOPOS+LEN-1`` must be less than + ``BIT_SIZE(FROM)``. + + :param FROM: + The type shall be ``INTEGER``. + + :param FROMPOS: + The type shall be ``INTEGER``. + + :param LEN: + The type shall be ``INTEGER``. + + :param TO: + The type shall be ``INTEGER``, of the + same kind as :samp:`{FROM}`. + + :param TOPOS: + The type shall be ``INTEGER``. + + Standard: + Fortran 90 and later, has overloads that are GNU extensions + + Class: + Elemental subroutine + + Syntax: + .. code-block:: fortran + + CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``MVBITS(A)`` + - ``INTEGER A`` + - ``INTEGER`` + - Fortran 90 and later + * - ``BMVBITS(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``IMVBITS(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JMVBITS(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KMVBITS(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`IBCLR`, + :ref:`IBSET`, + :ref:`IBITS`, + :ref:`IAND`, + :ref:`IOR`, + :ref:`IEOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/nearest.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/nearest.rst new file mode 100644 index 0000000..8c2292c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/nearest.rst @@ -0,0 +1,51 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: NEAREST, real number, nearest different, floating point, nearest different + +.. _nearest: + +NEAREST --- Nearest representable number +**************************************** + +.. function:: NEAREST(X, S) + + ``NEAREST(X, S)`` returns the processor-representable number nearest + to ``X`` in the direction indicated by the sign of ``S``. + + :param X: + Shall be of type ``REAL``. + + :param S: + Shall be of type ``REAL`` and + not equal to zero. + + :return: + The return value is of the same type as ``X``. If ``S`` is + positive, ``NEAREST`` returns the processor-representable number + greater than ``X`` and nearest to it. If ``S`` is negative, + ``NEAREST`` returns the processor-representable number smaller than + ``X`` and nearest to it. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = NEAREST(X, S) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/newline.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/newline.rst new file mode 100644 index 0000000..0c5a830 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/newline.rst @@ -0,0 +1,42 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: NEW_LINE, newline, output, newline + +.. _new_line: + +NEW_LINE --- New line character +******************************* + +.. function:: NEW_LINE(C) + + ``NEW_LINE(C)`` returns the new-line character. + + :param C: + The argument shall be a scalar or array of the + type ``CHARACTER``. + + :return: + Returns a :samp:`{CHARACTER}` scalar of length one with the new-line character of + the same kind as parameter :samp:`{C}`. + + Standard: + Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = NEW_LINE(C) + + Example: + .. code-block:: fortran + + program newline + implicit none + write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.' + end program newline
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/nint.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/nint.rst new file mode 100644 index 0000000..8c4eb56 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/nint.rst @@ -0,0 +1,75 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _nint: + +.. index:: NINT + +.. index:: IDNINT + +.. index:: rounding, nearest whole number + +NINT --- Nearest whole number +***************************** + +.. function:: NINT(A) + + ``NINT(A)`` rounds its argument to the nearest whole number. + + :param A: + The type of the argument shall be ``REAL``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + Returns :samp:`{A}` with the fractional portion of its magnitude eliminated by + rounding to the nearest whole number and with its sign preserved, + converted to an ``INTEGER`` of the default kind. + + Standard: + Fortran 77 and later, with :samp:`{KIND}` argument Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = NINT(A [, KIND]) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return Type + - Standard + + * - ``NINT(A)`` + - ``REAL(4) A`` + - ``INTEGER`` + - Fortran 77 and later + * - ``IDNINT(A)`` + - ``REAL(8) A`` + - ``INTEGER`` + - Fortran 77 and later + + See also: + :ref:`CEILING`, + :ref:`FLOOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/norm2.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/norm2.rst new file mode 100644 index 0000000..05bb491 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/norm2.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: NORM2, Euclidean vector norm, L2 vector norm, norm, Euclidean + +.. _norm2: + +NORM2 --- Euclidean vector norms +******************************** + +.. function:: NORM2(ARRAY, DIM) + + Calculates the Euclidean vector norm (L_2 norm) + of :samp:`{ARRAY}` along dimension :samp:`{DIM}`. + + :param ARRAY: + Shall be an array of type ``REAL`` + + :param DIM: + (Optional) shall be a scalar of type + ``INTEGER`` with a value in the range from 1 to n, where n + equals the rank of :samp:`{ARRAY}`. + + :return: + The result is of the same type as :samp:`{ARRAY}`. + + Standard: + Fortran 2008 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = NORM2(ARRAY[, DIM]) + + Example: + .. code-block:: fortran + + PROGRAM test_sum + REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ] + print *, NORM2(x) ! = sqrt(55.) ~ 7.416 + END PROGRAM
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/not.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/not.rst new file mode 100644 index 0000000..841b19c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/not.rst @@ -0,0 +1,85 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _not: + +.. index:: NOT + +.. index:: BNOT + +.. index:: INOT + +.. index:: JNOT + +.. index:: KNOT + +.. index:: bits, negate + +.. index:: bitwise logical not + +.. index:: logical not, bitwise + +NOT --- Logical negation +************************ + +.. function:: NOT() + + ``NOT`` returns the bitwise Boolean inverse of :samp:`{I}`. + + :param I: + The type shall be ``INTEGER``. + + :return: + The return type is ``INTEGER``, of the same kind as the + argument. + + Standard: + Fortran 90 and later, has overloads that are GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = NOT(I) + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``NOT(A)`` + - ``INTEGER A`` + - ``INTEGER`` + - Fortran 95 and later + * - ``BNOT(A)`` + - ``INTEGER(1) A`` + - ``INTEGER(1)`` + - GNU extension + * - ``INOT(A)`` + - ``INTEGER(2) A`` + - ``INTEGER(2)`` + - GNU extension + * - ``JNOT(A)`` + - ``INTEGER(4) A`` + - ``INTEGER(4)`` + - GNU extension + * - ``KNOT(A)`` + - ``INTEGER(8) A`` + - ``INTEGER(8)`` + - GNU extension + + See also: + :ref:`IAND`, + :ref:`IEOR`, + :ref:`IOR`, + :ref:`IBITS`, + :ref:`IBSET`, + :ref:`IBCLR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/null.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/null.rst new file mode 100644 index 0000000..816887e --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/null.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _null: + +NULL --- Function that returns an disassociated pointer +******************************************************* + +.. index:: NULL, pointer, status, pointer, disassociated + +.. function:: NULL(MOLD) + + Returns a disassociated pointer. + + :param MOLD: + (Optional) shall be a pointer of any association + status and of any type. + + :return: + A disassociated pointer. + + Standard: + Fortran 95 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + PTR => NULL([MOLD]) + + Example: + .. code-block:: fortran + + REAL, POINTER, DIMENSION(:) :: VEC => NULL () + + See also: + :ref:`ASSOCIATED`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/numimages.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/numimages.rst new file mode 100644 index 0000000..bcb93e0 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/numimages.rst @@ -0,0 +1,61 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: NUM_IMAGES, coarray, NUM_IMAGES, images, number of + +.. _num_images: + +NUM_IMAGES --- Function that returns the number of images +********************************************************* + +.. function:: NUM_IMAGES(DISTANCE, FAILED) + + Returns the number of images. + + :param DISTANCE: + (optional, intent(in)) Nonnegative scalar integer + + :param FAILED: + (optional, intent(in)) Scalar logical expression + + :return: + Scalar default-kind integer. If :samp:`{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 :samp:`{DISTANCE}` from the invoking + team. If :samp:`{DISTANCE}` is larger than the distance to the initial team, the + number of images of the initial team is returned. If :samp:`{FAILED}` is not present + the total number of images is returned; if it has the value ``.TRUE.``, + the number of failed images is returned, otherwise, the number of images which + do have not the failed status. + + Standard: + Fortran 2008 and later. With :samp:`{DISTANCE}` or :samp:`{FAILED}` argument, + Technical Specification (TS) 18508 or later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = NUM_IMAGES(DISTANCE, FAILED) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`THIS_IMAGE`, + :ref:`IMAGE_INDEX`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/or.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/or.rst new file mode 100644 index 0000000..2ca58a5 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/or.rst @@ -0,0 +1,60 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _or: + +OR --- Bitwise logical OR +************************* + +.. index:: OR, bitwise logical or, logical or, bitwise + +.. function:: OR(I, J) + + Bitwise logical ``OR``. + + :param I: + The type shall be either a scalar ``INTEGER`` + type or a scalar ``LOGICAL`` type or a boz-literal-constant. + + :param J: + The type shall be the same as the type of :samp:`{I}` or + a boz-literal-constant. :samp:`{I}` and :samp:`{J}` shall not both be + boz-literal-constants. If either :samp:`{I}` and :samp:`{J}` is a + boz-literal-constant, then the other argument must be a scalar ``INTEGER``. + + :return: + The return type is either a scalar ``INTEGER`` or a scalar + ``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 ``INTEGER`` with the kind type parameter of + the other argument as-if a call to :ref:`INT` occurred. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = OR(I, J) + + Example: + .. code-block:: fortran + + 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 + + See also: + Fortran 95 elemental function: + :ref:`IOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/pack.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/pack.rst new file mode 100644 index 0000000..183bb52 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/pack.rst @@ -0,0 +1,72 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: PACK, array, packing, array, reduce dimension, array, gather elements + +.. _pack: + +PACK --- Pack an array into an array of rank one +************************************************ + +.. function:: PACK(ARRAY, MASK,VECTOR) + + Stores the elements of :samp:`{ARRAY}` in an array of rank one. + + :param ARRAY: + Shall be an array of any type. + + :param MASK: + Shall be an array of type ``LOGICAL`` and + of the same size as :samp:`{ARRAY}`. Alternatively, it may be a ``LOGICAL`` + scalar. + + :param VECTOR: + (Optional) shall be an array of the same type + as :samp:`{ARRAY}` and of rank one. If present, the number of elements in + :samp:`{VECTOR}` shall be equal to or greater than the number of true elements + in :samp:`{MASK}`. If :samp:`{MASK}` is scalar, the number of elements in + :samp:`{VECTOR}` shall be equal to or greater than the number of elements in + :samp:`{ARRAY}`. + + :return: + The result is an array of rank one and the same type as that of :samp:`{ARRAY}`. + If :samp:`{VECTOR}` is present, the result size is that of :samp:`{VECTOR}`, the + number of ``TRUE`` values in :samp:`{MASK}` otherwise. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = PACK(ARRAY, MASK[,VECTOR]) + + Example: + Gathering nonzero elements from an array: + + .. code-block:: fortran + + 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 + + Gathering nonzero elements from an array and appending elements from :samp:`{VECTOR}` : + + .. code-block:: fortran + + 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 + + See also: + :ref:`UNPACK`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/parity.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/parity.rst new file mode 100644 index 0000000..6617c0f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/parity.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: PARITY, Parity, Reduction, XOR, XOR reduction + +.. _parity: + +PARITY --- Reduction with exclusive OR +************************************** + +.. function:: PARITY(MASK, DIM) + + Calculates the parity, i.e. the reduction using ``.XOR.``, + of :samp:`{MASK}` along dimension :samp:`{DIM}`. + + :param MASK: + Shall be an array of type ``LOGICAL`` + + :param DIM: + (Optional) shall be a scalar of type + ``INTEGER`` with a value in the range from 1 to n, where n + equals the rank of :samp:`{MASK}`. + + :return: + The result is of the same type as :samp:`{MASK}`. + + Standard: + Fortran 2008 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = PARITY(MASK[, DIM]) + + Example: + .. code-block:: fortran + + PROGRAM test_sum + LOGICAL :: x(2) = [ .true., .false. ] + print *, PARITY(x) ! prints "T" (true). + END PROGRAM
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/perror.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/perror.rst new file mode 100644 index 0000000..22e13e3 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/perror.rst @@ -0,0 +1,35 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: PERROR, system, error handling + +.. _perror: + +PERROR --- Print system error message +************************************* + +.. function:: PERROR(STRING) + + Prints (on the C ``stderr`` stream) a newline-terminated error + message corresponding to the last system error. This is prefixed by + :samp:`{STRING}`, a colon and a space. See ``perror(3)``. + + :param STRING: + A scalar of type ``CHARACTER`` and of the + default kind. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL PERROR(STRING) + + See also: + :ref:`IERRNO`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/popcnt.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/popcnt.rst new file mode 100644 index 0000000..5e9d19b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/popcnt.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: POPCNT, binary representation, bits set + +.. _popcnt: + +POPCNT --- Number of bits set +***************************** + +.. function:: POPCNT(I) + + ``POPCNT(I)`` returns the number of bits set ('1' bits) in the binary + representation of ``I``. + + :param I: + Shall be of type ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the default integer + kind. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = POPCNT(I) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`POPPAR`, + :ref:`LEADZ`, + :ref:`TRAILZ`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/poppar.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/poppar.rst new file mode 100644 index 0000000..85f1641 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/poppar.rst @@ -0,0 +1,50 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: POPPAR, binary representation, parity + +.. _poppar: + +POPPAR --- Parity of the number of bits set +******************************************* + +.. function:: POPPAR(I) + + ``POPPAR(I)`` returns parity of the integer ``I``, i.e. the parity + of the number of bits set ('1' bits) in the binary representation of + ``I``. It is equal to 0 if ``I`` has an even number of bits set, + and 1 for an odd number of '1' bits. + + :param I: + Shall be of type ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the default integer + kind. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = POPPAR(I) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`POPCNT`, + :ref:`LEADZ`, + :ref:`TRAILZ`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/precision.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/precision.rst new file mode 100644 index 0000000..892786a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/precision.rst @@ -0,0 +1,50 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: PRECISION, model representation, precision + +.. _precision: + +PRECISION --- Decimal precision of a real kind +********************************************** + +.. function:: PRECISION(X) + + ``PRECISION(X)`` returns the decimal precision in the model of the + type of ``X``. + + :param X: + Shall be of type ``REAL`` or ``COMPLEX``. It may + be scalar or valued. + + :return: + The return value is of type ``INTEGER`` and of the default integer + kind. + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = PRECISION(X) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`SELECTED_REAL_KIND`, + :ref:`RANGE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/present.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/present.rst new file mode 100644 index 0000000..c2f8f34 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/present.rst @@ -0,0 +1,47 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: PRESENT + +.. _present: + +PRESENT --- Determine whether an optional dummy argument is specified +********************************************************************* + +.. function:: PRESENT(A) + + Determines whether an optional dummy argument is present. + + :param A: + 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. + + :return: + Returns either ``TRUE`` if the optional argument :samp:`{A}` is present, or + ``FALSE`` otherwise. + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = PRESENT(A) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/product.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/product.rst new file mode 100644 index 0000000..81d59d6 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/product.rst @@ -0,0 +1,56 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: PRODUCT, array, product, array, multiply elements, array, conditionally multiply elements, multiply array elements + +.. _product: + +PRODUCT --- Product of array elements +************************************* + +.. function:: PRODUCT(ARRAY, DIM, MASK) + + Multiplies the elements of :samp:`{ARRAY}` along dimension :samp:`{DIM}` if + the corresponding element in :samp:`{MASK}` is ``TRUE``. + + :param ARRAY: + Shall be an array of type ``INTEGER``, + ``REAL`` or ``COMPLEX``. + + :param DIM: + (Optional) shall be a scalar of type + ``INTEGER`` with a value in the range from 1 to n, where n + equals the rank of :samp:`{ARRAY}`. + + :param MASK: + (Optional) shall be of type ``LOGICAL`` + and either be a scalar or an array of the same shape as :samp:`{ARRAY}`. + + :return: + The result is of the same type as :samp:`{ARRAY}`. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = PRODUCT(ARRAY[, MASK]) + RESULT = PRODUCT(ARRAY, DIM[, MASK]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`SUM`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/radix.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/radix.rst new file mode 100644 index 0000000..14379ce --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/radix.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: RADIX, model representation, base, model representation, radix + +.. _radix: + +RADIX --- Base of a model number +******************************** + +.. function:: RADIX(X) + + ``RADIX(X)`` returns the base of the model representing the entity :samp:`{X}`. + + :param X: + Shall be of type ``INTEGER`` or ``REAL`` + + :return: + The return value is a scalar of type ``INTEGER`` and of the default + integer kind. + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = RADIX(X) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`SELECTED_REAL_KIND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ran.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ran.rst new file mode 100644 index 0000000..deee7b0 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ran.rst @@ -0,0 +1,27 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _ran: + +RAN --- Real pseudo-random number +********************************* + +.. index:: RAN, random number generation + +.. function:: RAN() + + For compatibility with HP FORTRAN 77/iX, the ``RAN`` intrinsic is + provided as an alias for ``RAND``. See :ref:`RAND` for complete + documentation. + + Standard: + GNU extension + + Class: + Function + + See also: + :ref:`RAND`, + :ref:`RANDOM_NUMBER`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/rand.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/rand.rst new file mode 100644 index 0000000..c8fe878 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/rand.rst @@ -0,0 +1,51 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: RAND, random number generation + +.. _rand: + +RAND --- Real pseudo-random number +********************************** + +.. function:: RAND(FLAG) + + ``RAND(FLAG)`` returns a pseudo-random number from a uniform + distribution between 0 and 1. If :samp:`{FLAG}` is 0, the next number + in the current sequence is returned; if :samp:`{FLAG}` is 1, the generator + is restarted by ``CALL SRAND(0)`` ; if :samp:`{FLAG}` has any other value, + it is used as a new seed with ``SRAND``. + + :param I: + Shall be a scalar ``INTEGER`` of kind 4. + + :return: + The return value is of ``REAL`` type and the default kind. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = RAND(I) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`SRAND`, + :ref:`RANDOM_NUMBER`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/randominit.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/randominit.rst new file mode 100644 index 0000000..7e1ffd5 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/randominit.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: RANDOM_INIT, random number generation, initialization + +.. _random_init: + +RANDOM_INIT --- Initialize a pseudo-random number generator +*********************************************************** + +.. function:: RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT) + + Initializes the state of the pseudorandom number generator used by + ``RANDOM_NUMBER``. + + :param REPEATABLE: + Shall be a scalar with a ``LOGICAL`` type, + and it is ``INTENT(IN)``. If it is ``.true.``, the seed is set to + a processor-dependent value that is the same each time ``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 ``.false.``, the seed + is set to a processor-dependent value. + + :param IMAGE_DISTINCT: + Shall be a scalar with a + ``LOGICAL`` type, and it is ``INTENT(IN)``. If it is ``.true.``, + the seed is set to a processor-dependent value that is distinct from th + seed set by a call to ``RANDOM_INIT`` in another image. If it is + ``.false.``, the seed is set to a value that does depend which image called + ``RANDOM_INIT``. + + Standard: + Fortran 2018 + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`RANDOM_NUMBER`, + :ref:`RANDOM_SEED`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/randomnumber.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/randomnumber.rst new file mode 100644 index 0000000..77935c9 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/randomnumber.rst @@ -0,0 +1,42 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: RANDOM_NUMBER, random number generation + +.. _random_number: + +RANDOM_NUMBER --- Pseudo-random number +************************************** + +.. function:: RANDOM_NUMBER(HARVEST) + + Returns a single pseudorandom number or an array of pseudorandom numbers + from the uniform distribution over the range 0 \leq x < 1. + + :param HARVEST: + Shall be a scalar or an array of type ``REAL``. + + Standard: + Fortran 90 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL RANDOM_NUMBER(HARVEST) + + Example: + .. code-block:: fortran + + program test_random_number + REAL :: r(5,5) + CALL RANDOM_NUMBER(r) + end program + + See also: + :ref:`RANDOM_SEED`, + :ref:`RANDOM_INIT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/randomseed.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/randomseed.rst new file mode 100644 index 0000000..01b2b9f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/randomseed.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: RANDOM_SEED, random number generation, seeding, seeding a random number generator + +.. _random_seed: + +RANDOM_SEED --- Initialize a pseudo-random number sequence +********************************************************** + +.. function:: RANDOM_SEED(SIZE, PUT, GET) + + Restarts or queries the state of the pseudorandom number generator used by + ``RANDOM_NUMBER``. + + :param SIZE: + (Optional) Shall be a scalar and of type default + ``INTEGER``, with ``INTENT(OUT)``. It specifies the minimum size + of the arrays used with the :samp:`{PUT}` and :samp:`{GET}` arguments. + + :param PUT: + (Optional) Shall be an array of type default + ``INTEGER`` and rank one. It is ``INTENT(IN)`` and the size of + the array must be larger than or equal to the number returned by the + :samp:`{SIZE}` argument. + + :param GET: + (Optional) Shall be an array of type default + ``INTEGER`` and rank one. It is ``INTENT(OUT)`` and the size + of the array must be larger than or equal to the number returned by + the :samp:`{SIZE}` argument. + + Standard: + Fortran 90 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL RANDOM_SEED([SIZE, PUT, GET]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`RANDOM_NUMBER`, + :ref:`RANDOM_INIT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/range.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/range.rst new file mode 100644 index 0000000..1bfd6b9 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/range.rst @@ -0,0 +1,42 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: RANGE, model representation, range + +.. _range: + +RANGE --- Decimal exponent range +******************************** + +.. function:: RANGE(X) + + ``RANGE(X)`` returns the decimal exponent range in the model of the + type of ``X``. + + :param X: + Shall be of type ``INTEGER``, ``REAL`` + or ``COMPLEX``. + + :return: + The return value is of type ``INTEGER`` and of the default integer + kind. + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = RANGE(X) + + Example: + See ``PRECISION`` for an example. + + See also: + :ref:`SELECTED_REAL_KIND`, + :ref:`PRECISION`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/rank.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/rank.rst new file mode 100644 index 0000000..4f4ab02 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/rank.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: RANK, rank + +.. _rank: + +RANK --- Rank of a data object +****************************** + +.. function:: RANK(A) + + ``RANK(A)`` returns the rank of a scalar or array data object. + + :param A: + can be of any type + + :return: + The return value is of type ``INTEGER`` and of the default integer + kind. For arrays, their rank is returned; for scalars zero is returned. + + Standard: + Technical Specification (TS) 29113 + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = RANK(A) + + Example: + .. code-block:: fortran + + program test_rank + integer :: a + real, allocatable :: b(:,:) + + print *, rank(a), rank(b) ! Prints: 0 2 + end program test_rank
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/real.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/real.rst new file mode 100644 index 0000000..0f15f5c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/real.rst @@ -0,0 +1,104 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _real: + +.. index:: REAL + +.. index:: REALPART + +.. index:: FLOAT + +.. index:: DFLOAT + +.. index:: FLOATI + +.. index:: FLOATJ + +.. index:: FLOATK + +.. index:: SNGL + +.. index:: conversion, to real + +.. index:: complex numbers, real part + +REAL --- Convert to real type +****************************** + +.. function:: REAL(A [, KIND]) + + ``REAL(A [, KIND])`` converts its argument :samp:`{A}` to a real type. The + ``REALPART`` function is provided for compatibility with :command:`g77`, + and its use is strongly discouraged. + + :param A: + Shall be ``INTEGER``, ``REAL``, or + ``COMPLEX``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + These functions return a ``REAL`` variable or array under + the following rules: + + Standard: + Fortran 77 and later, with :samp:`{KIND}` argument Fortran 90 and later, has GNU extensions + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = REAL(A [, KIND]) + RESULT = REALPART(Z) + + Example: + .. code-block:: fortran + + program test_real + complex :: x = (1.0, 2.0) + print *, real(x), real(x,8), realpart(x) + end program test_real + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``FLOAT(A)`` + - ``INTEGER(4)`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DFLOAT(A)`` + - ``INTEGER(4)`` + - ``REAL(8)`` + - GNU extension + * - ``FLOATI(A)`` + - ``INTEGER(2)`` + - ``REAL(4)`` + - GNU extension (-fdec) + * - ``FLOATJ(A)`` + - ``INTEGER(4)`` + - ``REAL(4)`` + - GNU extension (-fdec) + * - ``FLOATK(A)`` + - ``INTEGER(8)`` + - ``REAL(4)`` + - GNU extension (-fdec) + * - ``SNGL(A)`` + - ``REAL(8)`` + - ``REAL(4)`` + - Fortran 77 and later + + See also: + :ref:`DBLE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/rename.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/rename.rst new file mode 100644 index 0000000..594cbd9 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/rename.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: RENAME, file system, rename file + +.. _rename: + +RENAME --- Rename a file +************************ + +.. function:: RENAME(PATH1, PATH2) + + Renames a file from file :samp:`{PATH1}` to :samp:`{PATH2}`. A null + character (``CHAR(0)``) can be used to mark the end of the names in + :samp:`{PATH1}` and :samp:`{PATH2}` ; otherwise, trailing blanks in the file + names are ignored. If the :samp:`{STATUS}` argument is supplied, it + contains 0 on success or a nonzero error code upon return; see + ``rename(2)``. + + :param PATH1: + Shall be of default ``CHARACTER`` type. + + :param PATH2: + Shall be of default ``CHARACTER`` type. + + :param STATUS: + (Optional) Shall be of default ``INTEGER`` type. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL RENAME(PATH1, PATH2 [, STATUS]) + STATUS = RENAME(PATH1, PATH2) + + See also: + :ref:`LINK`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/repeat.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/repeat.rst new file mode 100644 index 0000000..8fd52f6 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/repeat.rst @@ -0,0 +1,43 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: REPEAT, string, repeat, string, concatenate + +.. _repeat: + +REPEAT --- Repeated string concatenation +***************************************** + +.. function:: REPEAT(STRING, NCOPIES) + + Concatenates :samp:`{NCOPIES}` copies of a string. + + :param STRING: + Shall be scalar and of type ``CHARACTER``. + + :param NCOPIES: + Shall be scalar and of type ``INTEGER``. + + :return: + A new scalar of type ``CHARACTER`` built up from :samp:`{NCOPIES}` copies + of :samp:`{STRING}`. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = REPEAT(STRING, NCOPIES) + + Example: + .. code-block:: fortran + + program test_repeat + write(*,*) repeat("x", 5) ! "xxxxx" + end program
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/reshape.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/reshape.rst new file mode 100644 index 0000000..de975fd --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/reshape.rst @@ -0,0 +1,62 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: RESHAPE, array, change dimensions, array, transmogrify + +.. _reshape: + +RESHAPE --- Function to reshape an array +**************************************** + +.. function:: RESHAPE(SOURCE, SHAPE, PAD, ORDER) + + Reshapes :samp:`{SOURCE}` to correspond to :samp:`{SHAPE}`. If necessary, + the new array may be padded with elements from :samp:`{PAD}` or permuted + as defined by :samp:`{ORDER}`. + + :param SOURCE: + Shall be an array of any type. + + :param SHAPE: + Shall be of type ``INTEGER`` and an + array of rank one. Its values must be positive or zero. + + :param PAD: + (Optional) shall be an array of the same + type as :samp:`{SOURCE}`. + + :param ORDER: + (Optional) shall be of type ``INTEGER`` + and an array of the same shape as :samp:`{SHAPE}`. Its values shall + be a permutation of the numbers from 1 to n, where n is the size of + :samp:`{SHAPE}`. If :samp:`{ORDER}` is absent, the natural ordering shall + be assumed. + + :return: + The result is an array of shape :samp:`{SHAPE}` with the same type as + :samp:`{SOURCE}`. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER]) + + Example: + .. code-block:: fortran + + PROGRAM test_reshape + INTEGER, DIMENSION(4) :: x + WRITE(*,*) SHAPE(x) ! prints "4" + WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2" + END PROGRAM + + See also: + :ref:`SHAPE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/rrspacing.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/rrspacing.rst new file mode 100644 index 0000000..c287aaa --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/rrspacing.rst @@ -0,0 +1,38 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: RRSPACING, real number, relative spacing, floating point, relative spacing + +.. _rrspacing: + +RRSPACING --- Reciprocal of the relative spacing +************************************************ + +.. function:: RRSPACING(X) + + ``RRSPACING(X)`` returns the reciprocal of the relative spacing of + model numbers near :samp:`{X}`. + + :param X: + Shall be of type ``REAL``. + + :return: + The return value is of the same type and kind as :samp:`{X}`. + The value returned is equal to + ``ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)``. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = RRSPACING(X) + + See also: + :ref:`SPACING`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/rshift.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/rshift.rst new file mode 100644 index 0000000..34d0c6d --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/rshift.rst @@ -0,0 +1,50 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _rshift: + +RSHIFT --- Right shift bits +*************************** + +.. index:: RSHIFT, bits, shift right + +.. function:: RSHIFT(I, SHIFT) + + ``RSHIFT`` returns a value corresponding to :samp:`{I}` with all of the + bits shifted right by :samp:`{SHIFT}` places. :samp:`{SHIFT}` shall be + nonnegative and less than or equal to ``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. + + :param I: + The type shall be ``INTEGER``. + + :param SHIFT: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the same kind as + :samp:`{I}`. + + Standard: + GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = RSHIFT(I, SHIFT) + + See also: + :ref:`ISHFT`, + :ref:`ISHFTC`, + :ref:`LSHIFT`, + :ref:`SHIFTA`, + :ref:`SHIFTR`, + :ref:`SHIFTL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/sametypeas.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/sametypeas.rst new file mode 100644 index 0000000..9f19b37 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/sametypeas.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SAME_TYPE_AS + +.. _same_type_as: + +SAME_TYPE_AS --- Query dynamic types for equality +************************************************** + +.. function:: SAME_TYPE_AS(A, B) + + Query dynamic types for equality. + + :param A: + Shall be an object of extensible declared type or + unlimited polymorphic. + + :param B: + Shall be an object of extensible declared type or + unlimited polymorphic. + + :return: + 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. + + Standard: + Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = SAME_TYPE_AS(A, B) + + See also: + :ref:`EXTENDS_TYPE_OF`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/scale.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/scale.rst new file mode 100644 index 0000000..96ba1cf --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/scale.rst @@ -0,0 +1,45 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SCALE, real number, scale, floating point, scale + +.. _scale: + +SCALE --- Scale a real value +**************************** + +.. function:: SCALE(X,I) + + ``SCALE(X,I)`` returns ``X * RADIX(X)**I``. + + :param X: + The type of the argument shall be a ``REAL``. + + :param I: + The type of the argument shall be a ``INTEGER``. + + :return: + The return value is of the same type and kind as :samp:`{X}`. + Its value is ``X * RADIX(X)**I``. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SCALE(X, I) + + Example: + .. code-block:: fortran + + program test_scale + real :: x = 178.1387e-4 + integer :: i = 5 + print *, scale(x,i), x*radix(x)**i + end program test_scale
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/scan.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/scan.rst new file mode 100644 index 0000000..20d4a86 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/scan.rst @@ -0,0 +1,57 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SCAN, string, find subset + +.. _scan: + +SCAN --- Scan a string for the presence of a set of characters +************************************************************** + +.. function:: SCAN(STRING, SET, BACK , KIND) + + Scans a :samp:`{STRING}` for any of the characters in a :samp:`{SET}` + of characters. + + :param STRING: + Shall be of type ``CHARACTER``. + + :param SET: + Shall be of type ``CHARACTER``. + + :param BACK: + (Optional) shall be of type ``LOGICAL``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + + Standard: + Fortran 90 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SCAN(STRING, SET[, BACK [, KIND]]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`index-intrinsic`, + :ref:`VERIFY`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/secnds.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/secnds.rst new file mode 100644 index 0000000..984bef5 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/secnds.rst @@ -0,0 +1,52 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SECNDS, time, elapsed, elapsed time + +.. _secnds: + +SECNDS --- Time function +************************ + +.. function:: SECNDS(X) + + ``SECNDS(X)`` gets the time in seconds from the real-time system clock. + :samp:`{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. + + :param T: + Shall be of type ``REAL(4)``. + + :param X: + Shall be of type ``REAL(4)``. + + :return: + None + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = SECNDS (X) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/second.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/second.rst new file mode 100644 index 0000000..6c30045 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/second.rst @@ -0,0 +1,40 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SECOND, time, elapsed, elapsed time + +.. _second: + +SECOND --- CPU time function +**************************** + +.. function:: SECOND() + + Returns a ``REAL(4)`` value representing the elapsed CPU time in + seconds. This provides the same functionality as the standard + ``CPU_TIME`` intrinsic, and is only included for backwards + compatibility. + + :param TIME: + Shall be of type ``REAL(4)``. + + :return: + In either syntax, :samp:`{TIME}` is set to the process's current runtime in + seconds. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL SECOND(TIME) + TIME = SECOND() + + See also: + :ref:`CPU_TIME`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/selectedcharkind.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/selectedcharkind.rst new file mode 100644 index 0000000..f5321dd --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/selectedcharkind.rst @@ -0,0 +1,56 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SELECTED_CHAR_KIND, character kind, kind, character + +.. _selected_char_kind: + +SELECTED_CHAR_KIND --- Choose character kind +******************************************** + +.. function:: SELECTED_CHAR_KIND(NAME) + + ``SELECTED_CHAR_KIND(NAME)`` returns the kind value for the character + set named :samp:`{NAME}`, if a character set with such a name is supported, + or -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. + + :param NAME: + Shall be a scalar and of the default character type. + + Standard: + Fortran 2003 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = SELECTED_CHAR_KIND(NAME) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/selectedintkind.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/selectedintkind.rst new file mode 100644 index 0000000..6e302d1 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/selectedintkind.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SELECTED_INT_KIND, integer kind, kind, integer + +.. _selected_int_kind: + +SELECTED_INT_KIND --- Choose integer kind +***************************************** + +.. function:: SELECTED_INT_KIND(R) + + ``SELECTED_INT_KIND(R)`` return the kind value of the smallest integer + type that can represent all values ranging from -10^R (exclusive) + to 10^R (exclusive). If there is no integer kind that accommodates + this range, ``SELECTED_INT_KIND`` returns -1. + + :param R: + Shall be a scalar and of type ``INTEGER``. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = SELECTED_INT_KIND(R) + + Example: + .. code-block:: fortran + + 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
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/selectedrealkind.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/selectedrealkind.rst new file mode 100644 index 0000000..bf540f9 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/selectedrealkind.rst @@ -0,0 +1,67 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SELECTED_REAL_KIND, real kind, kind, real, radix, real + +.. _selected_real_kind: + +SELECTED_REAL_KIND --- Choose real kind +*************************************** + +.. function:: SELECTED_REAL_KIND(P,R) + + ``SELECTED_REAL_KIND(P,R)`` returns the kind value of a real data type + with decimal precision of at least ``P`` digits, exponent range of + at least ``R``, and with a radix of ``RADIX``. + + :param P: + (Optional) shall be a scalar and of type ``INTEGER``. + + :param R: + (Optional) shall be a scalar and of type ``INTEGER``. + + :param RADIX: + (Optional) shall be a scalar and of type ``INTEGER``. + + :return: + ``SELECTED_REAL_KIND`` returns the value of the kind type parameter of + a real data type with decimal precision of at least ``P`` digits, a + decimal exponent range of at least ``R``, and with the requested + ``RADIX``. If the ``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 + + Standard: + Fortran 90 and later, with ``RADIX`` Fortran 2008 or later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = SELECTED_REAL_KIND([P, R, RADIX]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`PRECISION`, + :ref:`RANGE`, + :ref:`RADIX`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/setexponent.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/setexponent.rst new file mode 100644 index 0000000..2769cf9 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/setexponent.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SET_EXPONENT, real number, set exponent, floating point, set exponent + +.. _set_exponent: + +SET_EXPONENT --- Set the exponent of the model +********************************************** + +.. function:: SET_EXPONENT(X, I) + + ``SET_EXPONENT(X, I)`` returns the real number whose fractional part + is that of :samp:`{X}` and whose exponent part is :samp:`{I}`. + + :param X: + Shall be of type ``REAL``. + + :param I: + Shall be of type ``INTEGER``. + + :return: + The return value is of the same type and kind as :samp:`{X}`. + The real number whose fractional part + is that of :samp:`{X}` and whose exponent part if :samp:`{I}` is returned; + it is ``FRACTION(X) * RADIX(X)**I``. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SET_EXPONENT(X, I) + + Example: + .. code-block:: fortran + + PROGRAM test_setexp + REAL :: x = 178.1387e-4 + INTEGER :: i = 17 + PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i + END PROGRAM
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/shape.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/shape.rst new file mode 100644 index 0000000..33b1cce --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/shape.rst @@ -0,0 +1,55 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SHAPE, array, shape + +.. _shape: + +SHAPE --- Determine the shape of an array +***************************************** + +.. function:: SHAPE(SOURCE , KIND) + + Determines the shape of an array. + + :param SOURCE: + Shall be an array or scalar of any type. + If :samp:`{SOURCE}` is a pointer it must be associated and allocatable + arrays must be allocated. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + An ``INTEGER`` array of rank one with as many elements as :samp:`{SOURCE}` + has dimensions. The elements of the resulting array correspond to the extend + of :samp:`{SOURCE}` along the respective dimensions. If :samp:`{SOURCE}` is a scalar, + the result is the rank one array of size zero. If :samp:`{KIND}` is absent, the + return value has the default integer kind otherwise the specified kind. + + Standard: + Fortran 90 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = SHAPE(SOURCE [, KIND]) + + Example: + .. code-block:: fortran + + PROGRAM test_shape + INTEGER, DIMENSION(-1:1, -1:2) :: A + WRITE(*,*) SHAPE(A) ! (/ 3, 4 /) + WRITE(*,*) SIZE(SHAPE(42)) ! (/ /) + END PROGRAM + + See also: + :ref:`RESHAPE`, + :ref:`SIZE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/shifta.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/shifta.rst new file mode 100644 index 0000000..e897cbe --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/shifta.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _shifta: + +SHIFTA --- Right shift with fill +******************************** + +.. index:: SHIFTA, bits, shift right, shift, right with fill + +.. function:: SHIFTA(I, SHIFT) + + ``SHIFTA`` returns a value corresponding to :samp:`{I}` with all of the + bits shifted right by :samp:`{SHIFT}` places. :samp:`{SHIFT}` that be + nonnegative and less than or equal to ``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. + + :param I: + The type shall be ``INTEGER``. + + :param SHIFT: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the same kind as + :samp:`{I}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SHIFTA(I, SHIFT) + + See also: + :ref:`SHIFTL`, + :ref:`SHIFTR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/shiftl.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/shiftl.rst new file mode 100644 index 0000000..5d160ca --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/shiftl.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _shiftl: + +SHIFTL --- Left shift +********************* + +.. index:: SHIFTL, bits, shift left, shift, left + +.. function:: SHIFTL(I, SHIFT) + + ``SHIFTL`` returns a value corresponding to :samp:`{I}` with all of the + bits shifted left by :samp:`{SHIFT}` places. :samp:`{SHIFT}` shall be + nonnegative and less than or equal to ``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. + + :param I: + The type shall be ``INTEGER``. + + :param SHIFT: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the same kind as + :samp:`{I}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SHIFTL(I, SHIFT) + + See also: + :ref:`SHIFTA`, + :ref:`SHIFTR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/shiftr.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/shiftr.rst new file mode 100644 index 0000000..6b12774 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/shiftr.rst @@ -0,0 +1,44 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _shiftr: + +SHIFTR --- Right shift +********************** + +.. index:: SHIFTR, bits, shift right, shift, right + +.. function:: SHIFTR(I, SHIFT) + + ``SHIFTR`` returns a value corresponding to :samp:`{I}` with all of the + bits shifted right by :samp:`{SHIFT}` places. :samp:`{SHIFT}` shall be + nonnegative and less than or equal to ``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. + + :param I: + The type shall be ``INTEGER``. + + :param SHIFT: + The type shall be ``INTEGER``. + + :return: + The return value is of type ``INTEGER`` and of the same kind as + :samp:`{I}`. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SHIFTR(I, SHIFT) + + See also: + :ref:`SHIFTA`, + :ref:`SHIFTL`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/sign.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/sign.rst new file mode 100644 index 0000000..04d0043 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/sign.rst @@ -0,0 +1,78 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _sign: + +.. index:: SIGN + +.. index:: ISIGN + +.. index:: DSIGN + +.. index:: sign copying + +SIGN --- Sign copying function +****************************** + +.. function:: SIGN(A,B) + + ``SIGN(A,B)`` returns the value of :samp:`{A}` with the sign of :samp:`{B}`. + + :param A: + Shall be of type ``INTEGER`` or ``REAL`` + + :param B: + Shall be of the same type and kind as :samp:`{A}`. + + :return: + The kind of the return value is that of :samp:`{A}` and :samp:`{B}`. + If B \ge 0 then the result is ``ABS(A)``, else + it is ``-ABS(A)``. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SIGN(A, B) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Arguments + - Return type + - Standard + + * - ``SIGN(A,B)`` + - ``REAL(4) A, B`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``ISIGN(A,B)`` + - ``INTEGER(4) A, B`` + - ``INTEGER(4)`` + - Fortran 77 and later + * - ``DSIGN(A,B)`` + - ``REAL(8) A, B`` + - ``REAL(8)`` + - Fortran 77 and later
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/signal.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/signal.rst new file mode 100644 index 0000000..0ae2b3b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/signal.rst @@ -0,0 +1,59 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _signal: + +SIGNAL --- Signal handling subroutine (or function) +*************************************************** + +.. index:: SIGNAL, system, signal handling + +.. function:: SIGNAL(NUMBER, HANDLER, STATUS) + + ``SIGNAL(NUMBER, HANDLER [, STATUS])`` causes external subroutine + :samp:`{HANDLER}` to be executed with a single integer argument when signal + :samp:`{NUMBER}` occurs. If :samp:`{HANDLER}` is an integer, it can be used to + turn off handling of signal :samp:`{NUMBER}` or revert to its default + action. See ``signal(2)``. + + :param NUMBER: + Shall be a scalar integer, with ``INTENT(IN)`` + + :param HANDLER: + Signal handler (``INTEGER FUNCTION`` or + ``SUBROUTINE``) or dummy/global ``INTEGER`` scalar. + ``INTEGER``. It is ``INTENT(IN)``. + + :param STATUS: + (Optional) :samp:`{STATUS}` shall be a scalar + integer. It has ``INTENT(OUT)``. + + :return: + The ``SIGNAL`` function returns the value returned by ``signal(2)``. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL SIGNAL(NUMBER, HANDLER [, STATUS]) + STATUS = SIGNAL(NUMBER, HANDLER) + + Example: + .. code-block:: fortran + + program test_signal + intrinsic signal + external handler_print + + call signal (12, handler_print) + call signal (10, 1) + + call sleep (30) + end program test_signal
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/sin.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/sin.rst new file mode 100644 index 0000000..264f57f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/sin.rst @@ -0,0 +1,89 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _sin: + +.. index:: SIN + +.. index:: DSIN + +.. index:: CSIN + +.. index:: ZSIN + +.. index:: CDSIN + +.. index:: trigonometric function, sine + +.. index:: sine + +SIN --- Sine function +********************** + +.. function:: SIN(X) + + ``SIN(X)`` computes the sine of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or + ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SIN(X) + + Example: + .. code-block:: fortran + + program test_sin + real :: x = 0.0 + x = sin(x) + end program test_sin + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``SIN(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DSIN(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later + * - ``CSIN(X)`` + - ``COMPLEX(4) X`` + - ``COMPLEX(4)`` + - Fortran 77 and later + * - ``ZSIN(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + * - ``CDSIN(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + + See also: + Inverse function: + :ref:`ASIN` + Degrees function: + :ref:`SIND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/sind.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/sind.rst new file mode 100644 index 0000000..8cafb10 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/sind.rst @@ -0,0 +1,89 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _sind: + +.. index:: SIND + +.. index:: DSIND + +.. index:: CSIND + +.. index:: ZSIND + +.. index:: CDSIND + +.. index:: trigonometric function, sine, degrees + +.. index:: sine, degrees + +SIND --- Sine function, degrees +******************************* + +.. function:: SIND(X) + + ``SIND(X)`` computes the sine of :samp:`{X}` in degrees. + + :param X: + The type shall be ``REAL`` or + ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`, and its value is in degrees. + + Standard: + GNU extension, enabled with :option:`-fdec-math`. + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SIND(X) + + Example: + .. code-block:: fortran + + program test_sind + real :: x = 0.0 + x = sind(x) + end program test_sind + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``SIND(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - GNU extension + * - ``DSIND(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + * - ``CSIND(X)`` + - ``COMPLEX(4) X`` + - ``COMPLEX(4)`` + - GNU extension + * - ``ZSIND(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + * - ``CDSIND(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + + See also: + Inverse function: + :ref:`ASIND` + Radians function: + :ref:`SIN`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/sinh.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/sinh.rst new file mode 100644 index 0000000..f748361 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/sinh.rst @@ -0,0 +1,66 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _sinh: + +.. index:: SINH + +.. index:: DSINH + +.. index:: hyperbolic sine + +.. index:: hyperbolic function, sine + +.. index:: sine, hyperbolic + +SINH --- Hyperbolic sine function +********************************** + +.. function:: SINH(X) + + ``SINH(X)`` computes the hyperbolic sine of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`. + + Standard: + Fortran 90 and later, for a complex argument Fortran 2008 or later, has + a GNU extension + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SINH(X) + + Example: + .. code-block:: fortran + + program test_sinh + real(8) :: x = - 1.0_8 + x = sinh(x) + end program test_sinh + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``DSINH(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 90 and later + + See also: + :ref:`ASINH`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/size.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/size.rst new file mode 100644 index 0000000..6196a1a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/size.rst @@ -0,0 +1,55 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SIZE, array, size, array, number of elements, array, count elements + +.. _size: + +SIZE --- Determine the size of an array +*************************************** + +.. function:: SIZE(ARRAY, DIM , KIND) + + Determine the extent of :samp:`{ARRAY}` along a specified dimension :samp:`{DIM}`, + or the total number of elements in :samp:`{ARRAY}` if :samp:`{DIM}` is absent. + + :param ARRAY: + Shall be an array of any type. If :samp:`{ARRAY}` is + a pointer it must be associated and allocatable arrays must be allocated. + + :param DIM: + (Optional) shall be a scalar of type ``INTEGER`` + and its value shall be in the range from 1 to n, where n equals the rank + of :samp:`{ARRAY}`. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + + Standard: + Fortran 90 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = SIZE(ARRAY[, DIM [, KIND]]) + + Example: + .. code-block:: fortran + + PROGRAM test_size + WRITE(*,*) SIZE((/ 1, 2 /)) ! 2 + END PROGRAM + + See also: + :ref:`SHAPE`, + :ref:`RESHAPE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/sizeof.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/sizeof.rst new file mode 100644 index 0000000..8870efc --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/sizeof.rst @@ -0,0 +1,58 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SIZEOF, expression size, size of an expression + +.. _sizeof: + +SIZEOF --- Size in bytes of an expression +***************************************** + +.. function:: SIZEOF(X) + + ``SIZEOF(X)`` calculates the number of bytes of storage the + expression ``X`` occupies. + + :param X: + The argument shall be of any type, rank or shape. + + :return: + The return value is of type integer and of the system-dependent kind + :samp:`{C_SIZE_T}` (from the :samp:`{ISO_C_BINDING}` module). Its value is the + number of bytes occupied by the argument. If the argument has the + ``POINTER`` attribute, the number of bytes of the storage area pointed + to is returned. If the argument is of a derived type with ``POINTER`` + or ``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. + + Standard: + GNU extension + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + N = SIZEOF(X) + + Example: + .. code-block:: fortran + + integer :: i + real :: r, s(5) + print *, (sizeof(s)/sizeof(r) == 5) + end + + The example will print ``.TRUE.`` unless you are using a platform + where default ``REAL`` variables are unusually padded. + + See also: + :ref:`C_SIZEOF`, + :ref:`STORAGE_SIZE`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/sleep.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/sleep.rst new file mode 100644 index 0000000..d87a498 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/sleep.rst @@ -0,0 +1,36 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SLEEP, delayed execution + +.. _sleep: + +SLEEP --- Sleep for the specified number of seconds +*************************************************** + +.. function:: SLEEP(SECONDS) + + Calling this subroutine causes the process to pause for :samp:`{SECONDS}` seconds. + + :param SECONDS: + The type shall be of default ``INTEGER``. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL SLEEP(SECONDS) + + Example: + .. code-block:: fortran + + program test_sleep + call sleep(5) + end
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/spacing.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/spacing.rst new file mode 100644 index 0000000..3cc0a86 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/spacing.rst @@ -0,0 +1,47 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SPACING, real number, relative spacing, floating point, relative spacing + +.. _spacing: + +SPACING --- Smallest distance between two numbers of a given type +***************************************************************** + +.. function:: SPACING(X) + + Determines the distance between the argument :samp:`{X}` and the nearest + adjacent number of the same type. + + :param X: + Shall be of type ``REAL``. + + :return: + The result is of the same type as the input argument :samp:`{X}`. + + Standard: + Fortran 90 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SPACING(X) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`RRSPACING`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/spread.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/spread.rst new file mode 100644 index 0000000..a0d914f --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/spread.rst @@ -0,0 +1,54 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SPREAD, array, increase dimension, array, duplicate elements, array, duplicate dimensions + +.. _spread: + +SPREAD --- Add a dimension to an array +************************************** + +.. function:: SPREAD(SOURCE, DIM, NCOPIES) + + Replicates a :samp:`{SOURCE}` array :samp:`{NCOPIES}` times along a specified + dimension :samp:`{DIM}`. + + :param SOURCE: + Shall be a scalar or an array of any type and + a rank less than seven. + + :param DIM: + Shall be a scalar of type ``INTEGER`` with a + value in the range from 1 to n+1, where n equals the rank of :samp:`{SOURCE}`. + + :param NCOPIES: + Shall be a scalar of type ``INTEGER``. + + :return: + The result is an array of the same type as :samp:`{SOURCE}` and has rank n+1 + where n equals the rank of :samp:`{SOURCE}`. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = SPREAD(SOURCE, DIM, NCOPIES) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`UNPACK`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/sqrt.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/sqrt.rst new file mode 100644 index 0000000..0acfabc --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/sqrt.rst @@ -0,0 +1,86 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _sqrt: + +.. index:: SQRT + +.. index:: DSQRT + +.. index:: CSQRT + +.. index:: ZSQRT + +.. index:: CDSQRT + +.. index:: root + +.. index:: square-root + +SQRT --- Square-root function +***************************** + +.. function:: SQRT(X) + + ``SQRT(X)`` computes the square root of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or + ``COMPLEX``. + + :return: + The return value is of type ``REAL`` or ``COMPLEX``. + The kind type parameter is the same as :samp:`{X}`. + + Standard: + Fortran 77 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = SQRT(X) + + Example: + .. code-block:: fortran + + 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 + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``SQRT(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DSQRT(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later + * - ``CSQRT(X)`` + - ``COMPLEX(4) X`` + - ``COMPLEX(4)`` + - Fortran 77 and later + * - ``ZSQRT(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension + * - ``CDSQRT(X)`` + - ``COMPLEX(8) X`` + - ``COMPLEX(8)`` + - GNU extension
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/srand.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/srand.rst new file mode 100644 index 0000000..3c74d88 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/srand.rst @@ -0,0 +1,53 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _srand: + +SRAND --- Reinitialize the random number generator +************************************************** + +.. index:: SRAND, random number generation, seeding, seeding a random number generator + +.. function:: SRAND(SEED) + + ``SRAND`` reinitializes the pseudo-random number generator + called by ``RAND`` and ``IRAND``. The new seed used by the + generator is specified by the required argument :samp:`{SEED}`. + + :param SEED: + Shall be a scalar ``INTEGER(kind=4)``. + + :return: + Does not return anything. + + Standard: + GNU extension + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL SRAND(SEED) + + Example: + See ``RAND`` and ``IRAND`` for examples. + + Notes: + The Fortran standard specifies the intrinsic subroutines + ``RANDOM_SEED`` to initialize the pseudo-random number + generator and ``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 (``RAND``, + ``IRAND`` and ``SRAND`` on the one hand, ``RANDOM_NUMBER`` and + ``RANDOM_SEED`` on the other hand) access two independent + pseudo-random number generators. + + See also: + :ref:`RAND`, + :ref:`RANDOM_SEED`, + :ref:`RANDOM_NUMBER`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/stat.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/stat.rst new file mode 100644 index 0000000..379854b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/stat.rst @@ -0,0 +1,72 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: STAT, file system, file status + +.. _stat: + +STAT --- Get file status +************************ + +.. function:: STAT(NAME, VALUES) + + 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. + + :param NAME: + The type shall be ``CHARACTER``, of the + default kind and a valid path within the file system. + + :param VALUES: + The type shall be ``INTEGER(4), DIMENSION(13)``. + + :param STATUS: + (Optional) status flag of type ``INTEGER(4)``. Returns 0 + on success and a system specific error code otherwise. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL STAT(NAME, VALUES [, STATUS]) + STATUS = STAT(NAME, VALUES) + + Example: + .. code-block:: fortran + + 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 + + See also: + To stat an open file: + :ref:`FSTAT` + To stat a link: + :ref:`LSTAT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/storagesize.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/storagesize.rst new file mode 100644 index 0000000..eca012b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/storagesize.rst @@ -0,0 +1,42 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: STORAGE_SIZE, storage size + +.. _storage_size: + +STORAGE_SIZE --- Storage size in bits +************************************* + +.. function:: STORAGE_SIZE(A , KIND) + + Returns the storage size of argument :samp:`{A}` in bits. + + :param A: + Shall be a scalar or array of any type. + + :param KIND: + (Optional) shall be a scalar integer constant expression. + + Standard: + Fortran 2008 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = STORAGE_SIZE(A [, KIND]) + + 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. + + See also: + :ref:`C_SIZEOF`, + :ref:`SIZEOF`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/sum.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/sum.rst new file mode 100644 index 0000000..ba4d0be --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/sum.rst @@ -0,0 +1,56 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SUM, array, sum, array, add elements, array, conditionally add elements, sum array elements + +.. _sum: + +SUM --- Sum of array elements +***************************** + +.. function:: SUM(ARRAY, DIM, MASK) + + Adds the elements of :samp:`{ARRAY}` along dimension :samp:`{DIM}` if + the corresponding element in :samp:`{MASK}` is ``TRUE``. + + :param ARRAY: + Shall be an array of type ``INTEGER``, + ``REAL`` or ``COMPLEX``. + + :param DIM: + (Optional) shall be a scalar of type + ``INTEGER`` with a value in the range from 1 to n, where n + equals the rank of :samp:`{ARRAY}`. + + :param MASK: + (Optional) shall be of type ``LOGICAL`` + and either be a scalar or an array of the same shape as :samp:`{ARRAY}`. + + :return: + The result is of the same type as :samp:`{ARRAY}`. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = SUM(ARRAY[, MASK]) + RESULT = SUM(ARRAY, DIM[, MASK]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`PRODUCT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/symlnk.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/symlnk.rst new file mode 100644 index 0000000..537560a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/symlnk.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SYMLNK, file system, create link, file system, soft link + +.. _symlnk: + +SYMLNK --- Create a symbolic link +********************************* + +.. function:: SYMLNK(PATH1, PATH2) + + Makes a symbolic link from file :samp:`{PATH1}` to :samp:`{PATH2}`. A null + character (``CHAR(0)``) can be used to mark the end of the names in + :samp:`{PATH1}` and :samp:`{PATH2}` ; otherwise, trailing blanks in the file + names are ignored. If the :samp:`{STATUS}` argument is supplied, it + contains 0 on success or a nonzero error code upon return; see + ``symlink(2)``. If the system does not supply ``symlink(2)``, + ``ENOSYS`` is returned. + + :param PATH1: + Shall be of default ``CHARACTER`` type. + + :param PATH2: + Shall be of default ``CHARACTER`` type. + + :param STATUS: + (Optional) Shall be of default ``INTEGER`` type. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL SYMLNK(PATH1, PATH2 [, STATUS]) + STATUS = SYMLNK(PATH1, PATH2) + + See also: + :ref:`LINK`, + :ref:`UNLINK`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/system.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/system.rst new file mode 100644 index 0000000..d111b94 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/system.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SYSTEM, system, system call + +.. _system: + +SYSTEM --- Execute a shell command +********************************** + +.. function:: SYSTEM(COMMAND) + + Passes the command :samp:`{COMMAND}` to a shell (see ``system(3)``). If + argument :samp:`{STATUS}` is present, it contains the value returned by + ``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. + + :param COMMAND: + Shall be of default ``CHARACTER`` type. + + :param STATUS: + (Optional) Shall be of default ``INTEGER`` type. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL SYSTEM(COMMAND [, STATUS]) + STATUS = SYSTEM(COMMAND) + + See also: + :ref:`EXECUTE_COMMAND_LINE`, which is part of the Fortran 2008 standard + and should considered in new code for future portability.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/systemclock.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/systemclock.rst new file mode 100644 index 0000000..2f42738 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/systemclock.rst @@ -0,0 +1,57 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: SYSTEM_CLOCK, time, clock ticks, clock ticks + +.. _system_clock: + +SYSTEM_CLOCK --- Time function +****************************** + +.. function:: SYSTEM_CLOCK(COUNT, COUNT_RATE, COUNT_MAX) + + Determines the :samp:`{COUNT}` of a processor clock since an unspecified + time in the past modulo :samp:`{COUNT_MAX}`, :samp:`{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. + + :param COUNT: + (Optional) shall be a scalar of type + ``INTEGER`` with ``INTENT(OUT)``. + + :param COUNT_RATE: + (Optional) shall be a scalar of type + ``INTEGER`` or ``REAL``, with ``INTENT(OUT)``. + + :param COUNT_MAX: + (Optional) shall be a scalar of type + ``INTEGER`` with ``INTENT(OUT)``. + + Standard: + Fortran 90 and later + + Class: + Subroutine + + Syntax: + .. code-block:: fortran + + CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`DATE_AND_TIME`, + :ref:`CPU_TIME`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/tan.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/tan.rst new file mode 100644 index 0000000..3788b2a --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/tan.rst @@ -0,0 +1,70 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _tan: + +.. index:: TAN + +.. index:: DTAN + +.. index:: trigonometric function, tangent + +.. index:: tangent + +TAN --- Tangent function +************************ + +.. function:: TAN(X) + + ``TAN(X)`` computes the tangent of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`, and its value is in radians. + + Standard: + Fortran 77 and later, for a complex argument Fortran 2008 or later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = TAN(X) + + Example: + .. code-block:: fortran + + program test_tan + real(8) :: x = 0.165_8 + x = tan(x) + end program test_tan + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``TAN(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DTAN(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later + + See also: + Inverse function: + :ref:`ATAN` + Degrees function: + :ref:`TAND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/tand.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/tand.rst new file mode 100644 index 0000000..a720c53 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/tand.rst @@ -0,0 +1,70 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _tand: + +.. index:: TAND + +.. index:: DTAND + +.. index:: trigonometric function, tangent, degrees + +.. index:: tangent, degrees + +TAND --- Tangent function, degrees +********************************** + +.. function:: TAND(X) + + ``TAND(X)`` computes the tangent of :samp:`{X}` in degrees. + + :param X: + The type shall be ``REAL`` or ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`, and its value is in degrees. + + Standard: + GNU extension, enabled with :option:`-fdec-math`. + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = TAND(X) + + Example: + .. code-block:: fortran + + program test_tand + real(8) :: x = 0.165_8 + x = tand(x) + end program test_tand + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``TAND(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - GNU extension + * - ``DTAND(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - GNU extension + + See also: + Inverse function: + :ref:`ATAND` + Radians function: + :ref:`TAN`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/tanh.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/tanh.rst new file mode 100644 index 0000000..d15bd8c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/tanh.rst @@ -0,0 +1,72 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _tanh: + +.. index:: TANH + +.. index:: DTANH + +.. index:: hyperbolic tangent + +.. index:: hyperbolic function, tangent + +.. index:: tangent, hyperbolic + +TANH --- Hyperbolic tangent function +************************************* + +.. function:: TANH(X) + + ``TANH(X)`` computes the hyperbolic tangent of :samp:`{X}`. + + :param X: + The type shall be ``REAL`` or ``COMPLEX``. + + :return: + The return value has same type and kind as :samp:`{X}`. If :samp:`{X}` is + complex, the imaginary part of the result is in radians. If :samp:`{X}` + is ``REAL``, the return value lies in the range + - 1 \leq tanh(x) \leq 1 . + + Standard: + Fortran 77 and later, for a complex argument Fortran 2008 or later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + X = TANH(X) + + Example: + .. code-block:: fortran + + program test_tanh + real(8) :: x = 2.1_8 + x = tanh(x) + end program test_tanh + + Specific names: + .. list-table:: + :header-rows: 1 + + * - Name + - Argument + - Return type + - Standard + + * - ``TANH(X)`` + - ``REAL(4) X`` + - ``REAL(4)`` + - Fortran 77 and later + * - ``DTANH(X)`` + - ``REAL(8) X`` + - ``REAL(8)`` + - Fortran 77 and later + + See also: + :ref:`ATANH`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/thisimage.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/thisimage.rst new file mode 100644 index 0000000..8dee8a4 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/thisimage.rst @@ -0,0 +1,75 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: THIS_IMAGE, coarray, THIS_IMAGE, images, index of this image + +.. _this_image: + +THIS_IMAGE --- Function that returns the cosubscript index of this image +************************************************************************ + +.. function:: THIS_IMAGE(COARRAY , DIM) + + Returns the cosubscript for this image. + + :param DISTANCE: + (optional, intent(in)) Nonnegative scalar integer + (not permitted together with :samp:`{COARRAY}`). + + :param COARRAY: + Coarray of any type (optional; if :samp:`{DIM}` + present, required). + + :param DIM: + default integer scalar (optional). If present, + :samp:`{DIM}` shall be between one and the corank of :samp:`{COARRAY}`. + + :return: + Default integer. If :samp:`{COARRAY}` is not present, it is scalar; if + :samp:`{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 :samp:`{DISTANCE}` from the invoking team. If + :samp:`{DISTANCE}` is larger than the distance to the initial team, the image + index of the initial team is returned. Otherwise when the :samp:`{COARRAY}` is + present, if :samp:`{DIM}` is not present, a rank-1 array with corank elements is + returned, containing the cosubscripts for :samp:`{COARRAY}` specifying the invoking + image. If :samp:`{DIM}` is present, a scalar is returned, with the value of + the :samp:`{DIM}` element of ``THIS_IMAGE(COARRAY)``. + + Standard: + Fortran 2008 and later. With :samp:`{DISTANCE}` argument, + Technical Specification (TS) 18508 or later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = THIS_IMAGE() + RESULT = THIS_IMAGE(DISTANCE) + RESULT = THIS_IMAGE(COARRAY [, DIM]) + + Example: + .. code-block:: fortran + + 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" + + See also: + :ref:`NUM_IMAGES`, + :ref:`IMAGE_INDEX`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/time.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/time.rst new file mode 100644 index 0000000..7b72b73 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/time.rst @@ -0,0 +1,39 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: TIME, time, current, current time + +.. _time: + +TIME --- Time function +********************** + +.. function:: TIME() + + Returns the current time encoded as an integer (in the manner of the + function ``time(3)`` in the C standard library). This value is + suitable for passing to :ref:`CTIME`, :ref:`GMTIME`, and :ref:`LTIME`. + + :return: + The return value is a scalar of type ``INTEGER(4)``. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = TIME() + + See also: + :ref:`DATE_AND_TIME`, + :ref:`CTIME`, + :ref:`GMTIME`, + :ref:`LTIME`, + :ref:`MCLOCK`, + :ref:`TIME8`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/time8.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/time8.rst new file mode 100644 index 0000000..029393d --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/time8.rst @@ -0,0 +1,39 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: TIME8, time, current, current time + +.. _time8: + +TIME8 --- Time function (64-bit) +******************************** + +.. function:: TIME8() + + Returns the current time encoded as an integer (in the manner of the + function ``time(3)`` in the C standard library). This value is + suitable for passing to :ref:`CTIME`, :ref:`GMTIME`, and :ref:`LTIME`. + + :return: + The return value is a scalar of type ``INTEGER(8)``. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = TIME8() + + See also: + :ref:`DATE_AND_TIME`, + :ref:`CTIME`, + :ref:`GMTIME`, + :ref:`LTIME`, + :ref:`MCLOCK8`, + :ref:`TIME`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/tiny.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/tiny.rst new file mode 100644 index 0000000..45c378b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/tiny.rst @@ -0,0 +1,36 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: TINY, limits, smallest number, model representation, smallest number + +.. _tiny: + +TINY --- Smallest positive number of a real kind +************************************************ + +.. function:: TINY(X) + + ``TINY(X)`` returns the smallest positive (non zero) number + in the model of the type of ``X``. + + :param X: + Shall be of type ``REAL``. + + :return: + The return value is of the same type and kind as :samp:`{X}` + + Standard: + Fortran 90 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = TINY(X) + + Example: + See ``HUGE`` for an example.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/trailz.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/trailz.rst new file mode 100644 index 0000000..b16b6de --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/trailz.rst @@ -0,0 +1,46 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _trailz: + +TRAILZ --- Number of trailing zero bits of an integer +***************************************************** + +.. index:: TRAILZ, zero bits + +.. function:: TRAILZ(I) + + ``TRAILZ`` returns the number of trailing zero bits of an integer. + + :param I: + Shall be of type ``INTEGER``. + + :return: + The type of the return value is the default ``INTEGER``. + If all the bits of ``I`` are zero, the result value is ``BIT_SIZE(I)``. + + Standard: + Fortran 2008 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = TRAILZ(I) + + Example: + .. code-block:: fortran + + PROGRAM test_trailz + WRITE (*,*) TRAILZ(8) ! prints 3 + END PROGRAM + + See also: + :ref:`BIT_SIZE`, + :ref:`LEADZ`, + :ref:`POPPAR`, + :ref:`POPCNT`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/transfer.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/transfer.rst new file mode 100644 index 0000000..51d8e94 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/transfer.rst @@ -0,0 +1,55 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: TRANSFER, bits, move, type cast + +.. _transfer: + +TRANSFER --- Transfer bit patterns +********************************** + +.. function:: TRANSFER(SOURCE, MOLD, SIZE) + + Interprets the bitwise representation of :samp:`{SOURCE}` in memory as if it + is the representation of a variable or array of the same type and type + parameters as :samp:`{MOLD}`. + + :param SOURCE: + Shall be a scalar or an array of any type. + + :param MOLD: + Shall be a scalar or an array of any type. + + :param SIZE: + (Optional) shall be a scalar of type + ``INTEGER``. + + :return: + The result has the same type as :samp:`{MOLD}`, with the bit level + representation of :samp:`{SOURCE}`. If :samp:`{SIZE}` is present, the result is + a one-dimensional array of length :samp:`{SIZE}`. If :samp:`{SIZE}` is absent + but :samp:`{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 :samp:`{SOURCE}`. If :samp:`{SIZE}` is absent + and :samp:`{MOLD}` is a scalar, the result is a scalar. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = TRANSFER(SOURCE, MOLD[, SIZE]) + + Example: + .. code-block:: fortran + + PROGRAM test_transfer + integer :: x = 2143289344 + print *, transfer(x, 1.0) ! prints "NaN" on i686 + END PROGRAM
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/transpose.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/transpose.rst new file mode 100644 index 0000000..7eada69 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/transpose.rst @@ -0,0 +1,34 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: TRANSPOSE, array, transpose, matrix, transpose, transpose + +.. _transpose: + +TRANSPOSE --- Transpose an array of rank two +******************************************** + +.. function:: TRANSPOSE(MATRIX) + + Transpose an array of rank two. Element (i, j) of the result has the value + ``MATRIX(j, i)``, for all i, j. + + :param MATRIX: + Shall be an array of any type and have a rank of two. + + :return: + The result has the same type as :samp:`{MATRIX}`, and has shape + ``(/ m, n /)`` if :samp:`{MATRIX}` has shape ``(/ n, m /)``. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = TRANSPOSE(MATRIX)
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/trim.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/trim.rst new file mode 100644 index 0000000..9e501af --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/trim.rst @@ -0,0 +1,45 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: TRIM, string, remove trailing whitespace + +.. _trim: + +TRIM --- Remove trailing blank characters of a string +***************************************************** + +.. function:: TRIM(STRING) + + Removes trailing blank characters of a string. + + :param STRING: + Shall be a scalar of type ``CHARACTER``. + + :return: + A scalar of type ``CHARACTER`` which length is that of :samp:`{STRING}` + less the number of trailing blanks. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = TRIM(STRING) + + Example: + .. code-block:: fortran + + PROGRAM test_trim + CHARACTER(len=10), PARAMETER :: s = "GFORTRAN " + WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks + END PROGRAM + + See also: + :ref:`ADJUSTL`, + :ref:`ADJUSTR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ttynam.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ttynam.rst new file mode 100644 index 0000000..4ca0572 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ttynam.rst @@ -0,0 +1,47 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: TTYNAM, system, terminal + +.. _ttynam: + +TTYNAM --- Get the name of a terminal device +******************************************** + +.. function:: TTYNAM(UNIT) + + Get the name of a terminal device. For more information, + see ``ttyname(3)``. + + :param UNIT: + Shall be a scalar ``INTEGER``. + + :param NAME: + Shall be of type ``CHARACTER``. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL TTYNAM(UNIT, NAME) + NAME = TTYNAM(UNIT) + + Example: + .. code-block:: fortran + + PROGRAM test_ttynam + INTEGER :: unit + DO unit = 1, 10 + IF (isatty(unit=unit)) write(*,*) ttynam(unit) + END DO + END PROGRAM + + See also: + :ref:`ISATTY`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ubound.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ubound.rst new file mode 100644 index 0000000..81f97053 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ubound.rst @@ -0,0 +1,52 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: UBOUND, array, upper bound + +.. _ubound: + +UBOUND --- Upper dimension bounds of an array +********************************************* + +.. function:: UBOUND(ARRAY , DIM , KIND) + + Returns the upper bounds of an array, or a single upper bound + along the :samp:`{DIM}` dimension. + + :param ARRAY: + Shall be an array, of any type. + + :param DIM: + (Optional) Shall be a scalar ``INTEGER``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + If :samp:`{DIM}` is absent, the result is an array of the upper bounds of + :samp:`{ARRAY}`. If :samp:`{DIM}` is present, the result is a scalar + corresponding to the upper bound of the array along that dimension. If + :samp:`{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. + + Standard: + Fortran 90 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = UBOUND(ARRAY [, DIM [, KIND]]) + + See also: + :ref:`LBOUND`, + :ref:`LCOBOUND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/ucobound.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/ucobound.rst new file mode 100644 index 0000000..9a0066b --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/ucobound.rst @@ -0,0 +1,48 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: UCOBOUND, coarray, upper bound + +.. _ucobound: + +UCOBOUND --- Upper codimension bounds of an array +************************************************* + +.. function:: UCOBOUND(COARRAY , DIM , KIND) + + Returns the upper cobounds of a coarray, or a single upper cobound + along the :samp:`{DIM}` codimension. + + :param ARRAY: + Shall be an coarray, of any type. + + :param DIM: + (Optional) Shall be a scalar ``INTEGER``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + If :samp:`{DIM}` is absent, the result is an array of the lower cobounds of + :samp:`{COARRAY}`. If :samp:`{DIM}` is present, the result is a scalar + corresponding to the lower cobound of the array along that codimension. + + Standard: + Fortran 2008 and later + + Class: + Inquiry function + + Syntax: + .. code-block:: fortran + + RESULT = UCOBOUND(COARRAY [, DIM [, KIND]]) + + See also: + :ref:`LCOBOUND`, + :ref:`LBOUND`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/umask.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/umask.rst new file mode 100644 index 0000000..ea94dd6 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/umask.rst @@ -0,0 +1,36 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: UMASK, file system, file creation mask + +.. _umask: + +UMASK --- Set the file creation mask +************************************ + +.. function:: UMASK(MASK) + + Sets the file creation mask to :samp:`{MASK}`. If called as a function, it + returns the old value. If called as a subroutine and argument :samp:`{OLD}` + if it is supplied, it is set to the old value. See ``umask(2)``. + + :param MASK: + Shall be a scalar of type ``INTEGER``. + + :param OLD: + (Optional) Shall be a scalar of type + ``INTEGER``. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL UMASK(MASK [, OLD]) + OLD = UMASK(MASK)
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/unlink.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/unlink.rst new file mode 100644 index 0000000..15a91af --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/unlink.rst @@ -0,0 +1,41 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: UNLINK, file system, remove file + +.. _unlink: + +UNLINK --- Remove a file from the file system +********************************************* + +.. function:: UNLINK(PATH) + + Unlinks the file :samp:`{PATH}`. A null character (``CHAR(0)``) can be + used to mark the end of the name in :samp:`{PATH}` ; otherwise, trailing + blanks in the file name are ignored. If the :samp:`{STATUS}` argument is + supplied, it contains 0 on success or a nonzero error code upon return; + see ``unlink(2)``. + + :param PATH: + Shall be of default ``CHARACTER`` type. + + :param STATUS: + (Optional) Shall be of default ``INTEGER`` type. + + Standard: + GNU extension + + Class: + Subroutine, function + + Syntax: + .. code-block:: fortran + + CALL UNLINK(PATH [, STATUS]) + STATUS = UNLINK(PATH) + + See also: + :ref:`LINK`, + :ref:`SYMLNK`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/unpack.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/unpack.rst new file mode 100644 index 0000000..21078b6 --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/unpack.rst @@ -0,0 +1,57 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: UNPACK, array, unpacking, array, increase dimension, array, scatter elements + +.. _unpack: + +UNPACK --- Unpack an array of rank one into an array +**************************************************** + +.. function:: UNPACK(VECTOR, MASK, FIELD) + + Store the elements of :samp:`{VECTOR}` in an array of higher rank. + + :param VECTOR: + Shall be an array of any type and rank one. It + shall have at least as many elements as :samp:`{MASK}` has ``TRUE`` values. + + :param MASK: + Shall be an array of type ``LOGICAL``. + + :param FIELD: + Shall be of the same type as :samp:`{VECTOR}` and have + the same shape as :samp:`{MASK}`. + + :return: + The resulting array corresponds to :samp:`{FIELD}` with ``TRUE`` elements + of :samp:`{MASK}` replaced by values from :samp:`{VECTOR}` in array element order. + + Standard: + Fortran 90 and later + + Class: + Transformational function + + Syntax: + .. code-block:: fortran + + RESULT = UNPACK(VECTOR, MASK, FIELD) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`PACK`, + :ref:`SPREAD`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/verify.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/verify.rst new file mode 100644 index 0000000..e4e9aeb --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/verify.rst @@ -0,0 +1,59 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: VERIFY, string, find missing set + +.. _verify: + +VERIFY --- Scan a string for characters not a given set +******************************************************* + +.. function:: VERIFY(STRING, SET, BACK , KIND) + + Verifies that all the characters in :samp:`{STRING}` belong to the set of + characters in :samp:`{SET}`. + + :param STRING: + Shall be of type ``CHARACTER``. + + :param SET: + Shall be of type ``CHARACTER``. + + :param BACK: + (Optional) shall be of type ``LOGICAL``. + + :param KIND: + (Optional) An ``INTEGER`` initialization + expression indicating the kind parameter of the result. + + :return: + The return value is of type ``INTEGER`` and of kind :samp:`{KIND}`. If + :samp:`{KIND}` is absent, the return value is of default integer kind. + + Standard: + Fortran 90 and later, with :samp:`{KIND}` argument Fortran 2003 and later + + Class: + Elemental function + + Syntax: + .. code-block:: fortran + + RESULT = VERIFY(STRING, SET[, BACK [, KIND]]) + + Example: + .. code-block:: fortran + + 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 + + See also: + :ref:`SCAN`, + :ref:`index-intrinsic`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/intrinsic-procedures/xor.rst b/gcc/fortran/doc/gfortran/intrinsic-procedures/xor.rst new file mode 100644 index 0000000..fee343c --- /dev/null +++ b/gcc/fortran/doc/gfortran/intrinsic-procedures/xor.rst @@ -0,0 +1,60 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: XOR, bitwise logical exclusive or, logical exclusive or, bitwise + +.. _xor: + +XOR --- Bitwise logical exclusive OR +************************************ + +.. function:: XOR(I, J) + + Bitwise logical exclusive or. + + :param I: + The type shall be either a scalar ``INTEGER`` + type or a scalar ``LOGICAL`` type or a boz-literal-constant. + + :param J: + The type shall be the same as the type of :samp:`{I}` or + a boz-literal-constant. :samp:`{I}` and :samp:`{J}` shall not both be + boz-literal-constants. If either :samp:`{I}` and :samp:`{J}` is a + boz-literal-constant, then the other argument must be a scalar ``INTEGER``. + + :return: + The return type is either a scalar ``INTEGER`` or a scalar + ``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 ``INTEGER`` with the kind type parameter of + the other argument as-if a call to :ref:`INT` occurred. + + Standard: + GNU extension + + Class: + Function + + Syntax: + .. code-block:: fortran + + RESULT = XOR(I, J) + + Example: + .. code-block:: fortran + + 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 + + See also: + Fortran 95 elemental function: + :ref:`IEOR`
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/introduction.rst b/gcc/fortran/doc/gfortran/introduction.rst new file mode 100644 index 0000000..3684e78 --- /dev/null +++ b/gcc/fortran/doc/gfortran/introduction.rst @@ -0,0 +1,18 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _introduction: + +Introduction +------------ + +.. The following duplicates the text on the TexInfo table of contents. + +.. toctree:: + :maxdepth: 2 + + about-gnu-fortran + gnu-fortran-and-gcc + standards
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/mixed-language-programming.rst b/gcc/fortran/doc/gfortran/mixed-language-programming.rst new file mode 100644 index 0000000..506fe0e --- /dev/null +++ b/gcc/fortran/doc/gfortran/mixed-language-programming.rst @@ -0,0 +1,37 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: Interoperability, Mixed-language programming + +.. _mixed-language-programming: + +Mixed-Language Programming +-------------------------- + +.. toctree:: + :maxdepth: 2 + + interoperability-with-c + gnu-fortran-compiler-directives + non-fortran-main-program + naming-and-argument-passing-conventions + +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 ``extern "C"`` on +the C++ side and ``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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/naming-and-argument-passing-conventions.rst b/gcc/fortran/doc/gfortran/naming-and-argument-passing-conventions.rst new file mode 100644 index 0000000..298bf0c --- /dev/null +++ b/gcc/fortran/doc/gfortran/naming-and-argument-passing-conventions.rst @@ -0,0 +1,178 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _naming-and-argument-passing-conventions: + +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 see :ref:`interoperability-with-c`. + +.. toctree:: + :maxdepth: 2 + + +.. _naming-conventions: + +Naming conventions +^^^^^^^^^^^^^^^^^^ + +According the Fortran standard, valid Fortran names consist of a letter +between ``A`` to ``Z``, ``a`` to ``z``, digits ``0``, +``1`` to ``9`` and underscores (``_``) with the restriction +that names may only start with a letter. As vendor extension, the +dollar sign (``$``) 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 (``_``); using :option:`-fno-underscoring` no +underscore is appended while ``-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 ``stdcall``, an at-sign ``@`` followed by an integer +number is appended. For the changing the calling convention, see +see :ref:`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 ``__BLNK__``. + +For procedures and variables declared in the specification space of a +module, the name is formed by ``__``, followed by the lower-cased +module name, ``_MOD_``, and the lower-cased Fortran name. Note that +no underscore is appended. + +.. _argument-passing-conventions: + +Argument passing conventions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Subroutines do not return a value (matching C99's ``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 ``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 ``_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 ``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 ``ALLOCATABLE`` and ``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 ``VALUE`` attribute: Scalar arguments +of the type ``INTEGER``, ``LOGICAL``, ``REAL`` and +``COMPLEX`` are passed by value according to the platform ABI. +(As vendor extension and not recommended, using ``%VAL()`` in the +call to a procedure has the same effect.) For ``TYPE(C_PTR)`` and +procedure pointers, the pointer itself is passed such that it can be +modified without affecting the caller. + +.. todo:: Document how VALUE is handled for CHARACTER, TYPE, + CLASS and arrays, i.e. whether the copy-in is done in the caller + or in the callee. + +For Boolean (``LOGICAL``) arguments, please note that GCC expects +only the integer value 0 and 1. If a GNU Fortran ``LOGICAL`` +variable contains another integer value, the result is undefined. +As some other Fortran compilers use -1 for ``.TRUE.``, +extra care has to be taken -- such as passing the value as +``INTEGER``. (The same value restriction also applies to other +front ends of GCC, e.g. to GCC's C99 compiler for ``_Bool`` +or GCC's Ada compiler for ``Boolean``.) + +For arguments of ``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 ``size_t`` (or +``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 ``int``. In +order to retain compatibility with older versions, one can e.g. for +the following Fortran procedure + +.. code-block:: fortran + + subroutine fstrlen (s, a) + character(len=*) :: s + integer :: a + print*, len(s) + end subroutine fstrlen + +define the corresponding C prototype as follows: + +.. code-block:: fortran + + #if __GNUC__ > 7 + typedef size_t fortran_charlen_t; + #else + typedef int fortran_charlen_t; + #endif + + void fstrlen_ (char*, int*, fortran_charlen_t); + +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, ``CHARACTER(len=1)`` result variables are +returned according to the platform ABI and no hidden length argument +is used for dummy arguments; with ``VALUE``, those variables are +passed by value. + +For ``OPTIONAL`` dummy arguments, an absent argument is denoted +by a NULL pointer, except for scalar dummy arguments of type +``INTEGER``, ``LOGICAL``, ``REAL`` and ``COMPLEX`` +which have the ``VALUE`` attribute. For those, a hidden Boolean +argument (``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 ``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 + +* Result variable, when the function result is passed by reference + +* Character length of the function result, if it is a of type + ``CHARACTER`` and no C binding is used + +* The arguments in the order in which they appear in the Fortran + declaration + +* The present status for optional arguments with value attribute, + which are internally passed by value + +* The character length and/or coarray token and offset for the first + argument which is a ``CHARACTER`` or a nonallocatable coarray dummy + argument, followed by the hidden arguments of the next dummy argument + of such a type
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/non-fortran-main-program.rst b/gcc/fortran/doc/gfortran/non-fortran-main-program.rst new file mode 100644 index 0000000..91e0ff8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/non-fortran-main-program.rst @@ -0,0 +1,251 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _non-fortran-main-program: + +Non-Fortran Main Program +************************ + +.. toctree:: + :maxdepth: 2 + + +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 ``PROGRAM`` with GNU Fortran, a function +with the name ``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 ``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 ``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 ``_gfortran_set_args`` and +``_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 ``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. + +.. index:: _gfortran_set_args, libgfortran initialization, set_args + +.. _gfortran_set_args: + +_gfortran_set_args --- Save command-line arguments +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_set_args (int argc, char *argv[]) + + ``_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 ``_gfortran_set_options``). + + :param argc: + number of command line argument strings + + :param argv: + the command-line argument strings; argv[0] + is the pathname of the executable itself. + + :samp:`{Example}:` + + .. code-block:: c + + int main (int argc, char *argv[]) + { + /* Initialize libgfortran. */ + _gfortran_set_args (argc, argv); + return 0; + } + +.. index:: _gfortran_set_options, libgfortran initialization, set_options + +.. _gfortran_set_options: + +_gfortran_set_options --- Set library option flags +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_set_options (int num, int options[]) + + ``_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 + see :ref:`code-gen-options`. Please note that not all flags are actually + used. + + :param num: + number of options passed + + :param argv: + The list of flag values + + :samp:`{option flag list}:` + + .. list-table:: + :widths: 15 85 + + * - :samp:`{option}` [0] + - 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) ``GFC_STD_F77`` (1), ``GFC_STD_F95_OBS`` (2), ``GFC_STD_F95_DEL`` (4), ``GFC_STD_F95`` (8), ``GFC_STD_F2003`` (16), ``GFC_STD_GNU`` (32), ``GFC_STD_LEGACY`` (64), ``GFC_STD_F2008`` (128), ``GFC_STD_F2008_OBS`` (256), ``GFC_STD_F2008_TS`` (512), ``GFC_STD_F2018`` (1024), ``GFC_STD_F2018_OBS`` (2048), and ``GFC_STD=F2018_DEL`` (4096). Default: ``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``. + * - :samp:`{option}` [1] + - Standard-warning flag; prints a warning to standard error. Default: ``GFC_STD_F95_DEL | GFC_STD_LEGACY``. + * - :samp:`{option}` [2] + - If non zero, enable pedantic checking. Default: off. + * - :samp:`{option}` [3] + - Unused. + * - :samp:`{option}` [4] + - 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 ``_gfortran_set_args``. + * - :samp:`{option}` [5] + - If non zero, supports signed zeros. Default: enabled. + * - :samp:`{option}` [6] + - 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. + * - :samp:`{option}` [7] + - Unused. + * - :samp:`{option}` [8] + - Show a warning when invoking ``STOP`` and ``ERROR STOP`` if a floating-point exception occurred. Possible values are (bitwise or-ed) ``GFC_FPE_INVALID`` (1), ``GFC_FPE_DENORMAL`` (2), ``GFC_FPE_ZERO`` (4), ``GFC_FPE_OVERFLOW`` (8), ``GFC_FPE_UNDERFLOW`` (16), ``GFC_FPE_INEXACT`` (32). Default: None (0). (Default in the compiler: ``GFC_FPE_INVALID | GFC_FPE_DENORMAL | GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW``.) + + :samp:`{Example}:` + + .. code-block:: c + + /* Use gfortran 4.9 default options. */ + static int options[] = {68, 511, 0, 0, 1, 1, 0, 0, 31}; + _gfortran_set_options (9, &options); + +.. index:: _gfortran_set_convert, libgfortran initialization, set_convert + +.. _gfortran_set_convert: + +_gfortran_set_convert --- Set endian conversion +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_set_convert (int conv) + + ``_gfortran_set_convert`` set the representation of data for + unformatted files. + + :param conv: + Endian conversion, possible values: + GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1), + GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3). + + :samp:`{Example}:` + + .. code-block:: c + + int main (int argc, char *argv[]) + { + /* Initialize libgfortran. */ + _gfortran_set_args (argc, argv); + _gfortran_set_convert (1); + return 0; + } + +.. index:: _gfortran_set_record_marker, libgfortran initialization, set_record_marker + +.. _gfortran_set_record_marker: + +_gfortran_set_record_marker --- Set length of record markers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_set_record_marker (int val) + + ``_gfortran_set_record_marker`` sets the length of record markers + for unformatted files. + + :param val: + Length of the record marker; valid values + are 4 and 8. Default is 4. + + :samp:`{Example}:` + + .. code-block:: c + + int main (int argc, char *argv[]) + { + /* Initialize libgfortran. */ + _gfortran_set_args (argc, argv); + _gfortran_set_record_marker (8); + return 0; + } + +.. index:: _gfortran_set_fpe, libgfortran initialization, set_fpe + +.. _gfortran_set_fpe: + +_gfortran_set_fpe --- Enable floating point exception traps +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_set_fpe (int val) + + ``_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. + + :param option} [0]: + IEEE exceptions. Possible values are + (bitwise or-ed) zero (0, default) no trapping, + ``GFC_FPE_INVALID`` (1), ``GFC_FPE_DENORMAL`` (2), + ``GFC_FPE_ZERO`` (4), ``GFC_FPE_OVERFLOW`` (8), + ``GFC_FPE_UNDERFLOW`` (16), and ``GFC_FPE_INEXACT`` (32). + + :samp:`{Example}:` + + .. code-block:: c + + 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; + } + +.. index:: _gfortran_set_max_subrecord_length, libgfortran initialization, set_max_subrecord_length + +.. _gfortran_set_max_subrecord_length: + +_gfortran_set_max_subrecord_length --- Set subrecord length +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. function:: void _gfortran_set_max_subrecord_length (int val) + + ``_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. + + :param val: + the maximum length for a subrecord; + the maximum permitted value is 2147483639, which is also + the default. + + :samp:`{Example}:` + + .. code-block:: c + + int main (int argc, char *argv[]) + { + /* Initialize libgfortran. */ + _gfortran_set_args (argc, argv); + _gfortran_set_max_subrecord_length (8); + return 0; + }
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/projects.rst b/gcc/fortran/doc/gfortran/projects.rst new file mode 100644 index 0000000..99d8e1e --- /dev/null +++ b/gcc/fortran/doc/gfortran/projects.rst @@ -0,0 +1,29 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _projects: + +Projects +******** + +*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. + +*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 + 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. + +*Missing features* + For a larger project, consider working on the missing features required for + Fortran language standards compliance (see :ref:`standards`), or contributing + to the implementation of extensions such as OpenMP (see :ref:`openmp`) or + OpenACC (see :ref:`openacc`) that are under active development. Again, + contributing test cases for these features is useful too!
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime.rst b/gcc/fortran/doc/gfortran/runtime.rst new file mode 100644 index 0000000..e83c300 --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime.rst @@ -0,0 +1,33 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: environment variable + +.. _runtime: + +Runtime: Influencing runtime behavior with environment variables +----------------------------------------------------------------- + +The behavior of the :command:`gfortran` can be influenced by +environment variables. + +Malformed environment variables are silently ignored. + +.. toctree:: + :maxdepth: 2 + + runtime/tmpdir + runtime/gfortranstdinunit + runtime/gfortranstdoutunit + runtime/gfortranstderrunit + runtime/gfortranunbufferedall + runtime/gfortranunbufferedpreconnected + runtime/gfortranshowlocus + runtime/gfortranoptionalplus + runtime/gfortranlistseparator + runtime/gfortranconvertunit + runtime/gfortranerrorbacktrace + runtime/gfortranformattedbuffersize + runtime/gfortranunformattedbuffersize
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranconvertunit.rst b/gcc/fortran/doc/gfortran/runtime/gfortranconvertunit.rst new file mode 100644 index 0000000..5ac40f8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranconvertunit.rst @@ -0,0 +1,97 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_convert_unit: + +GFORTRAN_CONVERT_UNIT---Set conversion for unformatted I/O +********************************************************** + +By setting the :envvar:`GFORTRAN_CONVERT_UNIT` variable, it is possible +to change the representation of data for unformatted files. +The syntax for the :envvar:`GFORTRAN_CONVERT_UNIT` variable for +most systems is: + +.. code-block:: + + 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 ; + +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 ``CONVERT`` specifier: + +* ``NATIVE`` Use the native format. This is the default. + +* ``SWAP`` Swap between little- and big-endian. + +* ``LITTLE_ENDIAN`` Use the little-endian format + for unformatted files. + +* ``BIG_ENDIAN`` Use the big-endian format for unformatted files. + +For POWER systems which support :option:`-mabi=ieeelongdouble`, +there are additional options, which can be combined with the +others with commas. Those are + +* ``R16_IEEE`` Use IEEE 128-bit format for ``REAL(KIND=16)``. + +* ``R16_IBM`` Use IBM ``long double`` format for + ``REAL(KIND=16)``. + +A missing mode for an exception is taken to mean ``BIG_ENDIAN``. +Examples of values for :envvar:`GFORTRAN_CONVERT_UNIT` are: + +* ``'big_endian'`` Do all unformatted I/O in big_endian mode. + +* ``'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. + +* ``'10-20'`` Units 10 to 20 are big-endian, the rest is native. + +* ``'big_endian,r16_ibm'`` Do all unformatted I/O in big-endian + mode and use IBM long double for output of ``REAL(KIND=16)`` values. + +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`: + +.. code-block:: shell-session + + $ gfortran foo.f90 + $ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out + +Example code for :command:`csh`: + +.. code-block:: shell-session + + % gfortran foo.f90 + % setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20' + % ./a.out + +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. + +See :ref:`convert-specifier`, for an alternative way to specify the +data representation for unformatted files. See :ref:`runtime-options`, for +setting a default data representation for the whole program. The +``CONVERT`` specifier overrides the :option:`-fconvert` compile options. + +.. note:: + + 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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranerrorbacktrace.rst b/gcc/fortran/doc/gfortran/runtime/gfortranerrorbacktrace.rst new file mode 100644 index 0000000..9b8c3e7 --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranerrorbacktrace.rst @@ -0,0 +1,16 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_error_backtrace: + +GFORTRAN_ERROR_BACKTRACE---Show backtrace on run-time errors +************************************************************ + +If the :envvar:`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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranformattedbuffersize.rst b/gcc/fortran/doc/gfortran/runtime/gfortranformattedbuffersize.rst new file mode 100644 index 0000000..329f921 --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranformattedbuffersize.rst @@ -0,0 +1,13 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_formatted_buffer_size: + +GFORTRAN_FORMATTED_BUFFER_SIZE---Set buffer size for formatted I/O +****************************************************************** + +The :envvar:`GFORTRAN_FORMATTED_BUFFER_SIZE` environment variable +specifies buffer size in bytes to be used for formatted output. +The default value is 8192.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranlistseparator.rst b/gcc/fortran/doc/gfortran/runtime/gfortranlistseparator.rst new file mode 100644 index 0000000..6eb2b18 --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranlistseparator.rst @@ -0,0 +1,21 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_list_separator: + +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 + +.. code-block:: shell-session + + $ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out + +when :command:`a.out` is the compiled Fortran program that you want to run. +Default is a single space.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranoptionalplus.rst b/gcc/fortran/doc/gfortran/runtime/gfortranoptionalplus.rst new file mode 100644 index 0000000..2f95f9f --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranoptionalplus.rst @@ -0,0 +1,15 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_optional_plus: + +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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranshowlocus.rst b/gcc/fortran/doc/gfortran/runtime/gfortranshowlocus.rst new file mode 100644 index 0000000..7656461 --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranshowlocus.rst @@ -0,0 +1,14 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_show_locus: + +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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranstderrunit.rst b/gcc/fortran/doc/gfortran/runtime/gfortranstderrunit.rst new file mode 100644 index 0000000..6a847af --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranstderrunit.rst @@ -0,0 +1,13 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_stderr_unit: + +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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranstdinunit.rst b/gcc/fortran/doc/gfortran/runtime/gfortranstdinunit.rst new file mode 100644 index 0000000..362ddbd --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranstdinunit.rst @@ -0,0 +1,13 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_stdin_unit: + +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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranstdoutunit.rst b/gcc/fortran/doc/gfortran/runtime/gfortranstdoutunit.rst new file mode 100644 index 0000000..a6863bc --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranstdoutunit.rst @@ -0,0 +1,13 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_stdout_unit: + +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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranunbufferedall.rst b/gcc/fortran/doc/gfortran/runtime/gfortranunbufferedall.rst new file mode 100644 index 0000000..6e8eee1 --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranunbufferedall.rst @@ -0,0 +1,15 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_unbuffered_all: + +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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranunbufferedpreconnected.rst b/gcc/fortran/doc/gfortran/runtime/gfortranunbufferedpreconnected.rst new file mode 100644 index 0000000..3a9f8e4 --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranunbufferedpreconnected.rst @@ -0,0 +1,15 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_unbuffered_preconnected: + +GFORTRAN_UNBUFFERED_PRECONNECTED---Do not buffer I/O on preconnected units +************************************************************************** + +The environment variable named :envvar:`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.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/gfortranunformattedbuffersize.rst b/gcc/fortran/doc/gfortran/runtime/gfortranunformattedbuffersize.rst new file mode 100644 index 0000000..fa26cf8 --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/gfortranunformattedbuffersize.rst @@ -0,0 +1,13 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _gfortran_unformatted_buffer_size: + +GFORTRAN_UNFORMATTED_BUFFER_SIZE---Set buffer size for unformatted I/O +********************************************************************** + +The :envvar:`GFORTRAN_UNFORMATTED_BUFFER_SIZE` environment variable +specifies buffer size in bytes to be used for unformatted output. +The default value is 131072.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/runtime/tmpdir.rst b/gcc/fortran/doc/gfortran/runtime/tmpdir.rst new file mode 100644 index 0000000..6c5625d --- /dev/null +++ b/gcc/fortran/doc/gfortran/runtime/tmpdir.rst @@ -0,0 +1,22 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _tmpdir: + +TMPDIR---Directory for scratch files +************************************ + +When opening a file with ``STATUS='SCRATCH'``, GNU Fortran tries to +create the file in one of the potential directories by testing each +directory in the order below. + +* The environment variable :envvar:`TMPDIR`, if it exists. + +* On the MinGW target, the directory returned by the ``GetTempPath`` + function. Alternatively, on the Cygwin target, the :envvar:`TMP` and + :envvar:`TEMP` environment variables, if they exist, in that order. + +* The ``P_tmpdir`` macro if it is defined, otherwise the directory + :samp:`/tmp`.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/standards.rst b/gcc/fortran/doc/gfortran/standards.rst new file mode 100644 index 0000000..eff1b18 --- /dev/null +++ b/gcc/fortran/doc/gfortran/standards.rst @@ -0,0 +1,130 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. index:: Standards + +.. _standards: + +Standards +********* + +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 `WG5 <http://www.nag.co.uk/sc22wg5/>`_. +Official Fortran standard documents are available for purchase +from ISO; a collection of free documents (typically final drafts) are +also available on the `wiki <https://gcc.gnu.org/wiki/GFortranStandards>`_. + +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 +``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, +https://openmp.org/specifications/). +There also is support for the OpenACC specification (targeting +version 2.6, https://www.openacc.org/). See +https://gcc.gnu.org/wiki/OpenACC for more information. + +.. index:: Varying length strings, strings, varying length, conditional compilation + +.. _fortran-95-status: + +Fortran 95 status +^^^^^^^^^^^^^^^^^ + +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 +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 ``ISO_VARYING_STRING`` and should be considered as +replacement. (Namely, allocatable or pointers of the type +``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 (http://www.daniellnagle.com/coco.html). + +.. _fortran-2003-status: + +Fortran 2003 status +^^^^^^^^^^^^^^^^^^^ + +GNU Fortran implements the Fortran 2003 (ISO/IEC 1539-1:2004) standard +except for finalization support, which is incomplete. +See the +`Fortran 2003 wiki page <https://gcc.gnu.org/wiki/Fortran2003>`_ for a full list +of new features introduced by Fortran 2003 and their implementation status. + +.. _fortran-2008-status: + +Fortran 2008 status +^^^^^^^^^^^^^^^^^^^ + +The GNU Fortran compiler supports almost all features of Fortran 2008; +the `Fortran 2008 wiki <https://gcc.gnu.org/wiki/Fortran2008Status>`_ +has some information about the current implementation status. +In particular, the following are not yet supported: + +* ``DO CONCURRENT`` and ``FORALL`` do not recognize a + type-spec in the loop header. + +* The change to permit any constant expression in subscripts and + nested implied-do limits in a ``DATA`` statement has not been implemented. + +.. _fortran-2018-status: + +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: + +* 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 ``SELECT RANK`` construct as well as the parts relating to + ``BIND(C)`` functions. + See also :ref:`further-interoperability-of-fortran-with-c`. + +* GNU Fortran supports a subset of features derived from ISO/IEC TS 18508:2015, + 'Additional Parallel Features in Fortran': + + * The new atomic ADD, CAS, FETCH and ADD/OR/XOR, OR and XOR intrinsics. + + * The ``CO_MIN`` and ``CO_MAX`` and ``SUM`` reduction intrinsics, + and the ``CO_BROADCAST`` and ``CO_REDUCE`` intrinsic, except that those + do not support polymorphic types or types with allocatable, pointer or + polymorphic components. + + * Events (``EVENT POST``, ``EVENT WAIT``, ``EVENT_QUERY``). + + * Failed images (``FAIL IMAGE``, ``IMAGE_STATUS``, + ``FAILED_IMAGES``, ``STOPPED_IMAGES``). + +* An ``ERROR STOP`` statement is permitted in a ``PURE`` + procedure. + +* GNU Fortran supports the ``IMPLICIT NONE`` statement with an + ``implicit-none-spec-list``. + +* The behavior of the ``INQUIRE`` statement with the ``RECL=`` + specifier now conforms to Fortran 2018.
\ No newline at end of file diff --git a/gcc/fortran/doc/gfortran/type-and-enum-abi-documentation.rst b/gcc/fortran/doc/gfortran/type-and-enum-abi-documentation.rst new file mode 100644 index 0000000..ec87873 --- /dev/null +++ b/gcc/fortran/doc/gfortran/type-and-enum-abi-documentation.rst @@ -0,0 +1,189 @@ +.. + Copyright 1988-2022 Free Software Foundation, Inc. + This is part of the GCC manual. + For copying conditions, see the copyright.rst file. + +.. _type-and-enum-abi-documentation: + +Type and enum ABI Documentation +******************************* + +.. toctree:: + :maxdepth: 2 + + +.. _caf_token_t: + +caf_token_t +^^^^^^^^^^^ + +Typedef of type ``void *`` on the compiler side. Can be any data +type on the library side. + +.. _caf_register_t: + +caf_register_t +^^^^^^^^^^^^^^ + +Indicates which kind of coarray variable should be registered. + +.. code-block:: c++ + + 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; + +The values ``CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY`` and +``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 +``_caf_is_present`` which used internally by the ``ALLOCATED`` +intrinsic. + +.. _caf_deregister_t: + +caf_deregister_t +^^^^^^^^^^^^^^^^ + +.. code-block:: c++ + + typedef enum caf_deregister_t { + CAF_DEREGTYPE_COARRAY_DEREGISTER, + CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY + } + caf_deregister_t; + +Allows to specifiy the type of deregistration of a coarray object. The +``CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY`` flag is only allowed for +allocatable components in derived type coarrays. + +.. _caf_reference_t: + +caf_reference_t +^^^^^^^^^^^^^^^ + +The structure used for implementing arbitrary reference chains. +A ``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 ``MODE``. + +.. code-block:: c++ + + 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; + +.. code-block:: c++ + + 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; + +.. code-block:: c++ + + /* 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; + +The references make up a single linked list of reference operations. The +``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. + +.. note:: + The member ``STATIC_ARRAY_TYPE`` is used only when the ``TYPE`` is + ``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 ``CAF_ARR_REF_VECTOR`` is not implemented in the front end for + descriptor-less arrays. The library caf_single has untested support for it. + +.. _caf_team_t: + +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.
\ No newline at end of file |