5550 lines
206 KiB
Plaintext
5550 lines
206 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename gfortran.info
|
|
@set copyrights-gfortran 1999-2017
|
|
|
|
@include gcc-common.texi
|
|
|
|
@settitle The GNU Fortran Compiler
|
|
|
|
@c Create a separate index for command line options
|
|
@defcodeindex op
|
|
@c Merge the standard indexes into a single one.
|
|
@syncodeindex fn cp
|
|
@syncodeindex vr cp
|
|
@syncodeindex ky cp
|
|
@syncodeindex pg cp
|
|
@syncodeindex tp cp
|
|
|
|
@c TODO: The following "Part" definitions are included here temporarily
|
|
@c until they are incorporated into the official Texinfo distribution.
|
|
@c They borrow heavily from Texinfo's \unnchapentry definitions.
|
|
|
|
@tex
|
|
\gdef\part#1#2{%
|
|
\pchapsepmacro
|
|
\gdef\thischapter{}
|
|
\begingroup
|
|
\vglue\titlepagetopglue
|
|
\titlefonts \rm
|
|
\leftline{Part #1:@* #2}
|
|
\vskip4pt \hrule height 4pt width \hsize \vskip4pt
|
|
\endgroup
|
|
\writetocentry{part}{#2}{#1}
|
|
}
|
|
\gdef\blankpart{%
|
|
\writetocentry{blankpart}{}{}
|
|
}
|
|
% Part TOC-entry definition for summary contents.
|
|
\gdef\dosmallpartentry#1#2#3#4{%
|
|
\vskip .5\baselineskip plus.2\baselineskip
|
|
\begingroup
|
|
\let\rm=\bf \rm
|
|
\tocentry{Part #2: #1}{\doshortpageno\bgroup#4\egroup}
|
|
\endgroup
|
|
}
|
|
\gdef\dosmallblankpartentry#1#2#3#4{%
|
|
\vskip .5\baselineskip plus.2\baselineskip
|
|
}
|
|
% Part TOC-entry definition for regular contents. This has to be
|
|
% equated to an existing entry to not cause problems when the PDF
|
|
% outline is created.
|
|
\gdef\dopartentry#1#2#3#4{%
|
|
\unnchapentry{Part #2: #1}{}{#3}{#4}
|
|
}
|
|
\gdef\doblankpartentry#1#2#3#4{}
|
|
@end tex
|
|
|
|
@c %**end of header
|
|
|
|
@c Use with @@smallbook.
|
|
|
|
@c %** start of document
|
|
|
|
@c Cause even numbered pages to be printed on the left hand side of
|
|
@c the page and odd numbered pages to be printed on the right hand
|
|
@c side of the page. Using this, you can print on both sides of a
|
|
@c sheet of paper and have the text on the same part of the sheet.
|
|
|
|
@c The text on right hand pages is pushed towards the right hand
|
|
@c margin and the text on left hand pages is pushed toward the left
|
|
@c hand margin.
|
|
@c (To provide the reverse effect, set bindingoffset to -0.75in.)
|
|
|
|
@c @tex
|
|
@c \global\bindingoffset=0.75in
|
|
@c \global\normaloffset =0.75in
|
|
@c @end tex
|
|
|
|
@copying
|
|
Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with the
|
|
Invariant Sections being ``Funding Free Software'', the Front-Cover
|
|
Texts being (a) (see below), and with the Back-Cover Texts being (b)
|
|
(see below). A copy of the license is included in the section entitled
|
|
``GNU Free Documentation License''.
|
|
|
|
(a) The FSF's Front-Cover Text is:
|
|
|
|
A GNU Manual
|
|
|
|
(b) The FSF's Back-Cover Text is:
|
|
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
|
software. Copies published by the Free Software Foundation raise
|
|
funds for GNU development.
|
|
@end copying
|
|
|
|
@ifinfo
|
|
@dircategory Software development
|
|
@direntry
|
|
* gfortran: (gfortran). The GNU Fortran Compiler.
|
|
@end direntry
|
|
This file documents the use and the internals of
|
|
the GNU Fortran compiler, (@command{gfortran}).
|
|
|
|
Published by the Free Software Foundation
|
|
51 Franklin Street, Fifth Floor
|
|
Boston, MA 02110-1301 USA
|
|
|
|
@insertcopying
|
|
@end ifinfo
|
|
|
|
|
|
@setchapternewpage odd
|
|
@titlepage
|
|
@title Using GNU Fortran
|
|
@versionsubtitle
|
|
@author The @t{gfortran} team
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Published by the Free Software Foundation@*
|
|
51 Franklin Street, Fifth Floor@*
|
|
Boston, MA 02110-1301, USA@*
|
|
@c Last printed ??ber, 19??.@*
|
|
@c Printed copies are available for $? each.@*
|
|
@c ISBN ???
|
|
@sp 1
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@c TODO: The following "Part" definitions are included here temporarily
|
|
@c until they are incorporated into the official Texinfo distribution.
|
|
|
|
@tex
|
|
\global\let\partentry=\dosmallpartentry
|
|
\global\let\blankpartentry=\dosmallblankpartentry
|
|
@end tex
|
|
@summarycontents
|
|
|
|
@tex
|
|
\global\let\partentry=\dopartentry
|
|
\global\let\blankpartentry=\doblankpartentry
|
|
@end tex
|
|
@contents
|
|
|
|
@page
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c TexInfo table of contents.
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top Introduction
|
|
@cindex Introduction
|
|
|
|
This manual documents the use of @command{gfortran},
|
|
the GNU Fortran compiler. You can find in this manual how to invoke
|
|
@command{gfortran}, as well as its features and incompatibilities.
|
|
|
|
@ifset DEVELOPMENT
|
|
@emph{Warning:} This document, and the compiler it describes, are still
|
|
under development. While efforts are made to keep it up-to-date, it might
|
|
not accurately reflect the status of the most recent GNU Fortran compiler.
|
|
@end ifset
|
|
|
|
@comment
|
|
@comment When you add a new menu item, please keep the right hand
|
|
@comment aligned to the same column. Do not use tabs. This provides
|
|
@comment better formatting.
|
|
@comment
|
|
@menu
|
|
* Introduction::
|
|
|
|
Part I: Invoking GNU Fortran
|
|
* Invoking GNU Fortran:: Command options supported by @command{gfortran}.
|
|
* Runtime:: Influencing runtime behavior with environment variables.
|
|
|
|
Part II: Language Reference
|
|
* Fortran 2003 and 2008 status:: Fortran 2003 and 2008 features supported by GNU Fortran.
|
|
* Compiler Characteristics:: User-visible implementation details.
|
|
* Extensions:: Language extensions implemented by GNU Fortran.
|
|
* Mixed-Language Programming:: Interoperability with C
|
|
* Coarray Programming::
|
|
* Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran.
|
|
* Intrinsic Modules:: Intrinsic modules supported by GNU Fortran.
|
|
|
|
* Contributing:: How you can help.
|
|
* Copying:: GNU General Public License says
|
|
how you can copy and share GNU Fortran.
|
|
* GNU Free Documentation License::
|
|
How you can copy and share this manual.
|
|
* Funding:: How to help assure continued work for free software.
|
|
* Option Index:: Index of command line options
|
|
* Keyword Index:: Index of concepts
|
|
@end menu
|
|
@end ifnottex
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Introduction
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
@c The following duplicates the text on the TexInfo table of contents.
|
|
@iftex
|
|
This manual documents the use of @command{gfortran}, the GNU Fortran
|
|
compiler. You can find in this manual how to invoke @command{gfortran},
|
|
as well as its features and incompatibilities.
|
|
|
|
@ifset DEVELOPMENT
|
|
@emph{Warning:} This document, and the compiler it describes, are still
|
|
under development. While efforts are made to keep it up-to-date, it
|
|
might not accurately reflect the status of the most recent GNU Fortran
|
|
compiler.
|
|
@end ifset
|
|
@end iftex
|
|
|
|
The GNU Fortran compiler front end was
|
|
designed initially as a free replacement for,
|
|
or alternative to, the Unix @command{f95} command;
|
|
@command{gfortran} is the command you will use to invoke the compiler.
|
|
|
|
@menu
|
|
* About GNU Fortran:: What you should know about the GNU Fortran compiler.
|
|
* GNU Fortran and GCC:: You can compile Fortran, C, or other programs.
|
|
* Preprocessing and conditional compilation:: The Fortran preprocessor
|
|
* GNU Fortran and G77:: Why we chose to start from scratch.
|
|
* Project Status:: Status of GNU Fortran, roadmap, proposed extensions.
|
|
* Standards:: Standards supported by GNU Fortran.
|
|
@end menu
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c About GNU Fortran
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node About GNU Fortran
|
|
@section About GNU Fortran
|
|
|
|
The GNU Fortran compiler supports the Fortran 77, 90 and 95 standards
|
|
completely, parts of the Fortran 2003 and Fortran 2008 standards, and
|
|
several vendor extensions. The development goal is to provide the
|
|
following features:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Read a user's program,
|
|
stored in a file and containing instructions written
|
|
in Fortran 77, Fortran 90, Fortran 95, Fortran 2003 or Fortran 2008.
|
|
This file contains @dfn{source code}.
|
|
|
|
@item
|
|
Translate the user's program into instructions a computer
|
|
can carry out more quickly than it takes to translate the
|
|
instructions in the first
|
|
place. The result after compilation of a program is
|
|
@dfn{machine code},
|
|
code designed to be efficiently translated and processed
|
|
by a machine such as your computer.
|
|
Humans usually are not as good writing machine code
|
|
as they are at writing Fortran (or C++, Ada, or Java),
|
|
because it is easy to make tiny mistakes writing machine code.
|
|
|
|
@item
|
|
Provide the user with information about the reasons why
|
|
the compiler is unable to create a binary from the source code.
|
|
Usually this will be the case if the source code is flawed.
|
|
The Fortran 90 standard requires that the compiler can point out
|
|
mistakes to the user.
|
|
An incorrect usage of the language causes an @dfn{error message}.
|
|
|
|
The compiler will also attempt to diagnose cases where the
|
|
user's program contains a correct usage of the language,
|
|
but instructs the computer to do something questionable.
|
|
This kind of diagnostics message is called a @dfn{warning message}.
|
|
|
|
@item
|
|
Provide optional information about the translation passes
|
|
from the source code to machine code.
|
|
This can help a user of the compiler to find the cause of
|
|
certain bugs which may not be obvious in the source code,
|
|
but may be more easily found at a lower level compiler output.
|
|
It also helps developers to find bugs in the compiler itself.
|
|
|
|
@item
|
|
Provide information in the generated machine code that can
|
|
make it easier to find bugs in the program (using a debugging tool,
|
|
called a @dfn{debugger}, such as the GNU Debugger @command{gdb}).
|
|
|
|
@item
|
|
Locate and gather machine code already generated to
|
|
perform actions requested by statements in the user's program.
|
|
This machine code is organized into @dfn{modules} and is located
|
|
and @dfn{linked} to the user program.
|
|
@end itemize
|
|
|
|
The GNU Fortran compiler consists of several components:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A version of the @command{gcc} command
|
|
(which also might be installed as the system's @command{cc} command)
|
|
that also understands and accepts Fortran source code.
|
|
The @command{gcc} command is the @dfn{driver} program for
|
|
all the languages in the GNU Compiler Collection (GCC);
|
|
With @command{gcc},
|
|
you can compile the source code of any language for
|
|
which a front end is available in GCC.
|
|
|
|
@item
|
|
The @command{gfortran} command itself,
|
|
which also might be installed as the
|
|
system's @command{f95} command.
|
|
@command{gfortran} is just another driver program,
|
|
but specifically for the Fortran compiler only.
|
|
The difference with @command{gcc} is that @command{gfortran}
|
|
will automatically link the correct libraries to your program.
|
|
|
|
@item
|
|
A collection of run-time libraries.
|
|
These libraries contain the machine code needed to support
|
|
capabilities of the Fortran language that are not directly
|
|
provided by the machine code generated by the
|
|
@command{gfortran} compilation phase,
|
|
such as intrinsic functions and subroutines,
|
|
and routines for interaction with files and the operating system.
|
|
@c and mechanisms to spawn,
|
|
@c unleash and pause threads in parallelized code.
|
|
|
|
@item
|
|
The Fortran compiler itself, (@command{f951}).
|
|
This is the GNU Fortran parser and code generator,
|
|
linked to and interfaced with the GCC backend library.
|
|
@command{f951} ``translates'' the source code to
|
|
assembler code. You would typically not use this
|
|
program directly;
|
|
instead, the @command{gcc} or @command{gfortran} driver
|
|
programs will call it for you.
|
|
@end itemize
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c GNU Fortran and GCC
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node GNU Fortran and GCC
|
|
@section GNU Fortran and GCC
|
|
@cindex GNU Compiler Collection
|
|
@cindex GCC
|
|
|
|
GNU Fortran is a part of GCC, the @dfn{GNU Compiler Collection}. GCC
|
|
consists of a collection of front ends for various languages, which
|
|
translate the source code into a language-independent form called
|
|
@dfn{GENERIC}. This is then processed by a common middle end which
|
|
provides optimization, and then passed to one of a collection of back
|
|
ends which generate code for different computer architectures and
|
|
operating systems.
|
|
|
|
Functionally, this is implemented with a driver program (@command{gcc})
|
|
which provides the command-line interface for the compiler. It calls
|
|
the relevant compiler front-end program (e.g., @command{f951} for
|
|
Fortran) for each file in the source code, and then calls the assembler
|
|
and linker as appropriate to produce the compiled output. In a copy of
|
|
GCC which has been compiled with Fortran language support enabled,
|
|
@command{gcc} will recognize files with @file{.f}, @file{.for}, @file{.ftn},
|
|
@file{.f90}, @file{.f95}, @file{.f03} and @file{.f08} extensions as
|
|
Fortran source code, and compile it accordingly. A @command{gfortran}
|
|
driver program is also provided, which is identical to @command{gcc}
|
|
except that it automatically links the Fortran runtime libraries into the
|
|
compiled program.
|
|
|
|
Source files with @file{.f}, @file{.for}, @file{.fpp}, @file{.ftn}, @file{.F},
|
|
@file{.FOR}, @file{.FPP}, and @file{.FTN} extensions are treated as fixed form.
|
|
Source files with @file{.f90}, @file{.f95}, @file{.f03}, @file{.f08},
|
|
@file{.F90}, @file{.F95}, @file{.F03} and @file{.F08} extensions are
|
|
treated as free form. The capitalized versions of either form are run
|
|
through preprocessing. Source files with the lower case @file{.fpp}
|
|
extension are also run through preprocessing.
|
|
|
|
This manual specifically documents the Fortran front end, which handles
|
|
the programming language's syntax and semantics. The aspects of GCC
|
|
which relate to the optimization passes and the back-end code generation
|
|
are documented in the GCC manual; see
|
|
@ref{Top,,Introduction,gcc,Using the GNU Compiler Collection (GCC)}.
|
|
The two manuals together provide a complete reference for the GNU
|
|
Fortran compiler.
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Preprocessing and conditional compilation
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Preprocessing and conditional compilation
|
|
@section Preprocessing and conditional compilation
|
|
@cindex CPP
|
|
@cindex FPP
|
|
@cindex Conditional compilation
|
|
@cindex Preprocessing
|
|
@cindex preprocessor, include file handling
|
|
|
|
Many Fortran compilers including GNU Fortran allow passing the source code
|
|
through a C preprocessor (CPP; sometimes also called the Fortran preprocessor,
|
|
FPP) to allow for conditional compilation. In the case of GNU Fortran,
|
|
this is the GNU C Preprocessor in the traditional mode. On systems with
|
|
case-preserving file names, the preprocessor is automatically invoked if the
|
|
filename extension is @file{.F}, @file{.FOR}, @file{.FTN}, @file{.fpp},
|
|
@file{.FPP}, @file{.F90}, @file{.F95}, @file{.F03} or @file{.F08}. To manually
|
|
invoke the preprocessor on any file, use @option{-cpp}, to disable
|
|
preprocessing on files where the preprocessor is run automatically, use
|
|
@option{-nocpp}.
|
|
|
|
If a preprocessed file includes another file with the Fortran @code{INCLUDE}
|
|
statement, the included file is not preprocessed. To preprocess included
|
|
files, use the equivalent preprocessor statement @code{#include}.
|
|
|
|
If GNU Fortran invokes the preprocessor, @code{__GFORTRAN__}
|
|
is defined and @code{__GNUC__}, @code{__GNUC_MINOR__} and
|
|
@code{__GNUC_PATCHLEVEL__} can be used to determine the version of the
|
|
compiler. See @ref{Top,,Overview,cpp,The C Preprocessor} for details.
|
|
|
|
While CPP is the de-facto standard for preprocessing Fortran code,
|
|
Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines
|
|
Conditional Compilation, which is not widely used and not directly
|
|
supported by the GNU Fortran compiler. You can use the program coco
|
|
to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}).
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c GNU Fortran and G77
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node GNU Fortran and G77
|
|
@section GNU Fortran and G77
|
|
@cindex Fortran 77
|
|
@cindex @command{g77}
|
|
|
|
The GNU Fortran compiler is the successor to @command{g77}, the Fortran
|
|
77 front end included in GCC prior to version 4. It is an entirely new
|
|
program that has been designed to provide Fortran 95 support and
|
|
extensibility for future Fortran language standards, as well as providing
|
|
backwards compatibility for Fortran 77 and nearly all of the GNU language
|
|
extensions supported by @command{g77}.
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Project Status
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Project Status
|
|
@section Project Status
|
|
|
|
@quotation
|
|
As soon as @command{gfortran} can parse all of the statements correctly,
|
|
it will be in the ``larva'' state.
|
|
When we generate code, the ``puppa'' state.
|
|
When @command{gfortran} is done,
|
|
we'll see if it will be a beautiful butterfly,
|
|
or just a big bug....
|
|
|
|
--Andy Vaught, April 2000
|
|
@end quotation
|
|
|
|
The start of the GNU Fortran 95 project was announced on
|
|
the GCC homepage in March 18, 2000
|
|
(even though Andy had already been working on it for a while,
|
|
of course).
|
|
|
|
The GNU Fortran compiler is able to compile nearly all
|
|
standard-compliant Fortran 95, Fortran 90, and Fortran 77 programs,
|
|
including a number of standard and non-standard extensions, and can be
|
|
used on real-world programs. In particular, the supported extensions
|
|
include OpenMP, Cray-style pointers, some old vendor extensions, and several
|
|
Fortran 2003 and Fortran 2008 features, including TR 15581. However, it is
|
|
still under development and has a few remaining rough edges.
|
|
There also is initial support for OpenACC.
|
|
Note that this is an experimental feature, incomplete, and subject to
|
|
change in future versions of GCC. See
|
|
@uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
|
|
|
|
At present, the GNU Fortran compiler passes the
|
|
@uref{http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html,
|
|
NIST Fortran 77 Test Suite}, and produces acceptable results on the
|
|
@uref{http://www.netlib.org/lapack/faq.html#1.21, LAPACK Test Suite}.
|
|
It also provides respectable performance on
|
|
the @uref{http://www.polyhedron.com/fortran-compiler-comparisons/polyhedron-benchmark-suite,
|
|
Polyhedron Fortran
|
|
compiler benchmarks} and the
|
|
@uref{http://www.netlib.org/benchmark/livermore,
|
|
Livermore Fortran Kernels test}. It has been used to compile a number of
|
|
large real-world programs, including
|
|
@uref{http://hirlam.org/, the HARMONIE and HIRLAM weather forecasting code} and
|
|
@uref{http://physical-chemistry.scb.uwa.edu.au/tonto/wiki/index.php/Main_Page,
|
|
the Tonto quantum chemistry package}; see
|
|
@url{https://gcc.gnu.org/@/wiki/@/GfortranApps} for an extended list.
|
|
|
|
Among other things, the GNU Fortran compiler is intended as a replacement
|
|
for G77. At this point, nearly all programs that could be compiled with
|
|
G77 can be compiled with GNU Fortran, although there are a few minor known
|
|
regressions.
|
|
|
|
The primary work remaining to be done on GNU Fortran falls into three
|
|
categories: bug fixing (primarily regarding the treatment of invalid code
|
|
and providing useful error messages), improving the compiler optimizations
|
|
and the performance of compiled code, and extending the compiler to support
|
|
future standards---in particular, Fortran 2003 and Fortran 2008.
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Standards
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Standards
|
|
@section Standards
|
|
@cindex Standards
|
|
|
|
@menu
|
|
* Varying Length Character Strings::
|
|
@end menu
|
|
|
|
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 have a partial support for ISO/IEC 1539-1:2004 (Fortran
|
|
2003), ISO/IEC 1539-1:2010 (Fortran 2008), the Technical Specification
|
|
@code{Further Interoperability of Fortran with C} (ISO/IEC TS 29113:2012).
|
|
Full support of those standards and future Fortran standards is planned.
|
|
The current status of the support is can be found in the
|
|
@ref{Fortran 2003 status}, @ref{Fortran 2008 status}, @ref{TS 29113 status}
|
|
and @ref{TS 18508 status} sections of the documentation.
|
|
|
|
Additionally, the GNU Fortran compilers supports the OpenMP specification
|
|
(version 4.0 and most of the features of the 4.5 version,
|
|
@url{http://openmp.org/@/wp/@/openmp-specifications/}).
|
|
There also is initial support for the OpenACC specification (targeting
|
|
version 2.0, @uref{http://www.openacc.org/}).
|
|
Note that this is an experimental feature, incomplete, and subject to
|
|
change in future versions of GCC. See
|
|
@uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
|
|
|
|
@node Varying Length Character Strings
|
|
@subsection Varying Length Character Strings
|
|
@cindex Varying length character strings
|
|
@cindex Varying length strings
|
|
@cindex strings, varying length
|
|
|
|
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. They can be found at
|
|
@uref{http://www.fortran.com/@/iso_varying_string.f95} and at
|
|
@uref{ftp://ftp.nag.co.uk/@/sc22wg5/@/ISO_VARYING_STRING/}.
|
|
|
|
Deferred-length character strings of Fortran 2003 supports part of
|
|
the features of @code{ISO_VARYING_STRING} and should be considered as
|
|
replacement. (Namely, allocatable or pointers of the type
|
|
@code{character(len=:)}.)
|
|
|
|
|
|
@c =====================================================================
|
|
@c PART I: INVOCATION REFERENCE
|
|
@c =====================================================================
|
|
|
|
@tex
|
|
\part{I}{Invoking GNU Fortran}
|
|
@end tex
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Compiler Options
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@include invoke.texi
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Runtime
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Runtime
|
|
@chapter Runtime: Influencing runtime behavior with environment variables
|
|
@cindex environment variable
|
|
|
|
The behavior of the @command{gfortran} can be influenced by
|
|
environment variables.
|
|
|
|
Malformed environment variables are silently ignored.
|
|
|
|
@menu
|
|
* TMPDIR:: Directory for scratch files
|
|
* GFORTRAN_STDIN_UNIT:: Unit number for standard input
|
|
* GFORTRAN_STDOUT_UNIT:: Unit number for standard output
|
|
* GFORTRAN_STDERR_UNIT:: Unit number for standard error
|
|
* GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units.
|
|
* GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units.
|
|
* GFORTRAN_SHOW_LOCUS:: Show location for runtime errors
|
|
* GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted
|
|
* GFORTRAN_DEFAULT_RECL:: Default record length for new files
|
|
* GFORTRAN_LIST_SEPARATOR:: Separator for list output
|
|
* GFORTRAN_CONVERT_UNIT:: Set endianness for unformatted I/O
|
|
* GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors
|
|
@end menu
|
|
|
|
@node TMPDIR
|
|
@section @env{TMPDIR}---Directory for scratch files
|
|
|
|
When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to
|
|
create the file in one of the potential directories by testing each
|
|
directory in the order below.
|
|
|
|
@enumerate
|
|
@item
|
|
The environment variable @env{TMPDIR}, if it exists.
|
|
|
|
@item
|
|
On the MinGW target, the directory returned by the @code{GetTempPath}
|
|
function. Alternatively, on the Cygwin target, the @env{TMP} and
|
|
@env{TEMP} environment variables, if they exist, in that order.
|
|
|
|
@item
|
|
The @code{P_tmpdir} macro if it is defined, otherwise the directory
|
|
@file{/tmp}.
|
|
@end enumerate
|
|
|
|
@node GFORTRAN_STDIN_UNIT
|
|
@section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input
|
|
|
|
This environment variable can be used to select the unit number
|
|
preconnected to standard input. This must be a positive integer.
|
|
The default value is 5.
|
|
|
|
@node GFORTRAN_STDOUT_UNIT
|
|
@section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output
|
|
|
|
This environment variable can be used to select the unit number
|
|
preconnected to standard output. This must be a positive integer.
|
|
The default value is 6.
|
|
|
|
@node GFORTRAN_STDERR_UNIT
|
|
@section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error
|
|
|
|
This environment variable can be used to select the unit number
|
|
preconnected to standard error. This must be a positive integer.
|
|
The default value is 0.
|
|
|
|
@node GFORTRAN_UNBUFFERED_ALL
|
|
@section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units
|
|
|
|
This environment variable controls whether all I/O is unbuffered. If
|
|
the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is
|
|
unbuffered. This will slow down small sequential reads and writes. If
|
|
the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered.
|
|
This is the default.
|
|
|
|
@node GFORTRAN_UNBUFFERED_PRECONNECTED
|
|
@section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units
|
|
|
|
The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls
|
|
whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) is unbuffered. If
|
|
the first letter is @samp{y}, @samp{Y} or @samp{1}, I/O is unbuffered. This
|
|
will slow down small sequential reads and writes. If the first letter
|
|
is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. This is the default.
|
|
|
|
@node GFORTRAN_SHOW_LOCUS
|
|
@section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors
|
|
|
|
If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and
|
|
line numbers for runtime errors are printed. If the first letter is
|
|
@samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers
|
|
for runtime errors. The default is to print the location.
|
|
|
|
@node GFORTRAN_OPTIONAL_PLUS
|
|
@section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted
|
|
|
|
If the first letter is @samp{y}, @samp{Y} or @samp{1},
|
|
a plus sign is printed
|
|
where permitted by the Fortran standard. If the first letter
|
|
is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed
|
|
in most cases. Default is not to print plus signs.
|
|
|
|
@node GFORTRAN_DEFAULT_RECL
|
|
@section @env{GFORTRAN_DEFAULT_RECL}---Default record length for new files
|
|
|
|
This environment variable specifies the default record length, in
|
|
bytes, for files which are opened without a @code{RECL} tag in the
|
|
@code{OPEN} statement. This must be a positive integer. The
|
|
default value is 1073741824 bytes (1 GB).
|
|
|
|
@node GFORTRAN_LIST_SEPARATOR
|
|
@section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output
|
|
|
|
This environment variable specifies the separator when writing
|
|
list-directed output. It may contain any number of spaces and
|
|
at most one comma. If you specify this on the command line,
|
|
be sure to quote spaces, as in
|
|
@smallexample
|
|
$ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out
|
|
@end smallexample
|
|
when @command{a.out} is the compiled Fortran program that you want to run.
|
|
Default is a single space.
|
|
|
|
@node GFORTRAN_CONVERT_UNIT
|
|
@section @env{GFORTRAN_CONVERT_UNIT}---Set endianness for unformatted I/O
|
|
|
|
By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible
|
|
to change the representation of data for unformatted files.
|
|
The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable is:
|
|
@smallexample
|
|
GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ;
|
|
mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ;
|
|
exception: mode ':' unit_list | unit_list ;
|
|
unit_list: unit_spec | unit_list unit_spec ;
|
|
unit_spec: INTEGER | INTEGER '-' INTEGER ;
|
|
@end smallexample
|
|
The variable consists of an optional default mode, followed by
|
|
a list of optional exceptions, which are separated by semicolons
|
|
from the preceding default and each other. Each exception consists
|
|
of a format and a comma-separated list of units. Valid values for
|
|
the modes are the same as for the @code{CONVERT} specifier:
|
|
|
|
@itemize @w{}
|
|
@item @code{NATIVE} Use the native format. This is the default.
|
|
@item @code{SWAP} Swap between little- and big-endian.
|
|
@item @code{LITTLE_ENDIAN} Use the little-endian format
|
|
for unformatted files.
|
|
@item @code{BIG_ENDIAN} Use the big-endian format for unformatted files.
|
|
@end itemize
|
|
A missing mode for an exception is taken to mean @code{BIG_ENDIAN}.
|
|
Examples of values for @env{GFORTRAN_CONVERT_UNIT} are:
|
|
@itemize @w{}
|
|
@item @code{'big_endian'} Do all unformatted I/O in big_endian mode.
|
|
@item @code{'little_endian;native:10-20,25'} Do all unformatted I/O
|
|
in little_endian mode, except for units 10 to 20 and 25, which are in
|
|
native format.
|
|
@item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native.
|
|
@end itemize
|
|
|
|
Setting the environment variables should be done on the command
|
|
line or via the @command{export}
|
|
command for @command{sh}-compatible shells and via @command{setenv}
|
|
for @command{csh}-compatible shells.
|
|
|
|
Example for @command{sh}:
|
|
@smallexample
|
|
$ gfortran foo.f90
|
|
$ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out
|
|
@end smallexample
|
|
|
|
Example code for @command{csh}:
|
|
@smallexample
|
|
% gfortran foo.f90
|
|
% setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20'
|
|
% ./a.out
|
|
@end smallexample
|
|
|
|
Using anything but the native representation for unformatted data
|
|
carries a significant speed overhead. If speed in this area matters
|
|
to you, it is best if you use this only for data that needs to be
|
|
portable.
|
|
|
|
@xref{CONVERT specifier}, for an alternative way to specify the
|
|
data representation for unformatted files. @xref{Runtime Options}, for
|
|
setting a default data representation for the whole program. The
|
|
@code{CONVERT} specifier overrides the @option{-fconvert} compile options.
|
|
|
|
@emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
|
|
environment variable will override the CONVERT specifier in the
|
|
open statement}. This is to give control over data formats to
|
|
users who do not have the source code of their program available.
|
|
|
|
@node GFORTRAN_ERROR_BACKTRACE
|
|
@section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors
|
|
|
|
If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to @samp{y},
|
|
@samp{Y} or @samp{1} (only the first letter is relevant) then a
|
|
backtrace is printed when a serious run-time error occurs. To disable
|
|
the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}.
|
|
Default is to print a backtrace unless the @option{-fno-backtrace}
|
|
compile option was used.
|
|
|
|
@c =====================================================================
|
|
@c PART II: LANGUAGE REFERENCE
|
|
@c =====================================================================
|
|
|
|
@tex
|
|
\part{II}{Language Reference}
|
|
@end tex
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Fortran 2003 and 2008 Status
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Fortran 2003 and 2008 status
|
|
@chapter Fortran 2003 and 2008 Status
|
|
|
|
@menu
|
|
* Fortran 2003 status::
|
|
* Fortran 2008 status::
|
|
* TS 29113 status::
|
|
* TS 18508 status::
|
|
@end menu
|
|
|
|
@node Fortran 2003 status
|
|
@section Fortran 2003 status
|
|
|
|
GNU Fortran supports several Fortran 2003 features; an incomplete
|
|
list can be found below. See also the
|
|
@uref{https://gcc.gnu.org/wiki/Fortran2003, wiki page} about Fortran 2003.
|
|
|
|
@itemize
|
|
@item Procedure pointers including procedure-pointer components with
|
|
@code{PASS} attribute.
|
|
|
|
@item Procedures which are bound to a derived type (type-bound procedures)
|
|
including @code{PASS}, @code{PROCEDURE} and @code{GENERIC}, and
|
|
operators bound to a type.
|
|
|
|
@item Abstract interfaces and type extension with the possibility to
|
|
override type-bound procedures or to have deferred binding.
|
|
|
|
@item Polymorphic entities (``@code{CLASS}'') for derived types and unlimited
|
|
polymorphism (``@code{CLASS(*)}'') -- including @code{SAME_TYPE_AS},
|
|
@code{EXTENDS_TYPE_OF} and @code{SELECT TYPE} for scalars and arrays and
|
|
finalization.
|
|
|
|
@item Generic interface names, which have the same name as derived types,
|
|
are now supported. This allows one to write constructor functions. Note
|
|
that Fortran does not support static constructor functions. For static
|
|
variables, only default initialization or structure-constructor
|
|
initialization are available.
|
|
|
|
@item The @code{ASSOCIATE} construct.
|
|
|
|
@item Interoperability with C including enumerations,
|
|
|
|
@item In structure constructors the components with default values may be
|
|
omitted.
|
|
|
|
@item Extensions to the @code{ALLOCATE} statement, allowing for a
|
|
type-specification with type parameter and for allocation and initialization
|
|
from a @code{SOURCE=} expression; @code{ALLOCATE} and @code{DEALLOCATE}
|
|
optionally return an error message string via @code{ERRMSG=}.
|
|
|
|
@item Reallocation on assignment: If an intrinsic assignment is
|
|
used, an allocatable variable on the left-hand side is automatically allocated
|
|
(if unallocated) or reallocated (if the shape is different). Currently, scalar
|
|
deferred character length left-hand sides are correctly handled but arrays
|
|
are not yet fully implemented.
|
|
|
|
@item Deferred-length character variables and scalar deferred-length character
|
|
components of derived types are supported. (Note that array-valued compoents
|
|
are not yet implemented.)
|
|
|
|
@item Transferring of allocations via @code{MOVE_ALLOC}.
|
|
|
|
@item The @code{PRIVATE} and @code{PUBLIC} attributes may be given individually
|
|
to derived-type components.
|
|
|
|
@item In pointer assignments, the lower bound may be specified and
|
|
the remapping of elements is supported.
|
|
|
|
@item For pointers an @code{INTENT} may be specified which affect the
|
|
association status not the value of the pointer target.
|
|
|
|
@item Intrinsics @code{command_argument_count}, @code{get_command},
|
|
@code{get_command_argument}, and @code{get_environment_variable}.
|
|
|
|
@item Support for Unicode characters (ISO 10646) and UTF-8, including
|
|
the @code{SELECTED_CHAR_KIND} and @code{NEW_LINE} intrinsic functions.
|
|
|
|
@item Support for binary, octal and hexadecimal (BOZ) constants in the
|
|
intrinsic functions @code{INT}, @code{REAL}, @code{CMPLX} and @code{DBLE}.
|
|
|
|
@item Support for namelist variables with allocatable and pointer
|
|
attribute and nonconstant length type parameter.
|
|
|
|
@item
|
|
@cindex array, constructors
|
|
@cindex @code{[...]}
|
|
Array constructors using square brackets. That is, @code{[...]} rather
|
|
than @code{(/.../)}. Type-specification for array constructors like
|
|
@code{(/ some-type :: ... /)}.
|
|
|
|
@item Extensions to the specification and initialization expressions,
|
|
including the support for intrinsics with real and complex arguments.
|
|
|
|
@item Support for the asynchronous input/output syntax; however, the
|
|
data transfer is currently always synchronously performed.
|
|
|
|
@item
|
|
@cindex @code{FLUSH} statement
|
|
@cindex statement, @code{FLUSH}
|
|
@code{FLUSH} statement.
|
|
|
|
@item
|
|
@cindex @code{IOMSG=} specifier
|
|
@code{IOMSG=} specifier for I/O statements.
|
|
|
|
@item
|
|
@cindex @code{ENUM} statement
|
|
@cindex @code{ENUMERATOR} statement
|
|
@cindex statement, @code{ENUM}
|
|
@cindex statement, @code{ENUMERATOR}
|
|
@opindex @code{fshort-enums}
|
|
Support for the declaration of enumeration constants via the
|
|
@code{ENUM} and @code{ENUMERATOR} statements. Interoperability with
|
|
@command{gcc} is guaranteed also for the case where the
|
|
@command{-fshort-enums} command line option is given.
|
|
|
|
@item
|
|
@cindex TR 15581
|
|
TR 15581:
|
|
@itemize
|
|
@item
|
|
@cindex @code{ALLOCATABLE} dummy arguments
|
|
@code{ALLOCATABLE} dummy arguments.
|
|
@item
|
|
@cindex @code{ALLOCATABLE} function results
|
|
@code{ALLOCATABLE} function results
|
|
@item
|
|
@cindex @code{ALLOCATABLE} components of derived types
|
|
@code{ALLOCATABLE} components of derived types
|
|
@end itemize
|
|
|
|
@item
|
|
@cindex @code{STREAM} I/O
|
|
@cindex @code{ACCESS='STREAM'} I/O
|
|
The @code{OPEN} statement supports the @code{ACCESS='STREAM'} specifier,
|
|
allowing I/O without any record structure.
|
|
|
|
@item
|
|
Namelist input/output for internal files.
|
|
|
|
@item Minor I/O features: Rounding during formatted output, using of
|
|
a decimal comma instead of a decimal point, setting whether a plus sign
|
|
should appear for positive numbers. On systems where @code{strtod} honours
|
|
the rounding mode, the rounding mode is also supported for input.
|
|
|
|
@item
|
|
@cindex @code{PROTECTED} statement
|
|
@cindex statement, @code{PROTECTED}
|
|
The @code{PROTECTED} statement and attribute.
|
|
|
|
@item
|
|
@cindex @code{VALUE} statement
|
|
@cindex statement, @code{VALUE}
|
|
The @code{VALUE} statement and attribute.
|
|
|
|
@item
|
|
@cindex @code{VOLATILE} statement
|
|
@cindex statement, @code{VOLATILE}
|
|
The @code{VOLATILE} statement and attribute.
|
|
|
|
@item
|
|
@cindex @code{IMPORT} statement
|
|
@cindex statement, @code{IMPORT}
|
|
The @code{IMPORT} statement, allowing to import
|
|
host-associated derived types.
|
|
|
|
@item The intrinsic modules @code{ISO_FORTRAN_ENVIRONMENT} is supported,
|
|
which contains parameters of the I/O units, storage sizes. Additionally,
|
|
procedures for C interoperability are available in the @code{ISO_C_BINDING}
|
|
module.
|
|
|
|
@item
|
|
@cindex @code{USE, INTRINSIC} statement
|
|
@cindex statement, @code{USE, INTRINSIC}
|
|
@cindex @code{ISO_FORTRAN_ENV} statement
|
|
@cindex statement, @code{ISO_FORTRAN_ENV}
|
|
@code{USE} statement with @code{INTRINSIC} and @code{NON_INTRINSIC}
|
|
attribute; supported intrinsic modules: @code{ISO_FORTRAN_ENV},
|
|
@code{ISO_C_BINDING}, @code{OMP_LIB} and @code{OMP_LIB_KINDS},
|
|
and @code{OPENACC}.
|
|
|
|
@item
|
|
Renaming of operators in the @code{USE} statement.
|
|
|
|
@end itemize
|
|
|
|
|
|
@node Fortran 2008 status
|
|
@section Fortran 2008 status
|
|
|
|
The latest version of the Fortran standard is ISO/IEC 1539-1:2010, informally
|
|
known as Fortran 2008. The official version is available from International
|
|
Organization for Standardization (ISO) or its national member organizations.
|
|
The the final draft (FDIS) can be downloaded free of charge from
|
|
@url{http://www.nag.co.uk/@/sc22wg5/@/links.html}. Fortran is developed by the
|
|
Working Group 5 of Sub-Committee 22 of the Joint Technical Committee 1 of the
|
|
International Organization for Standardization and the International
|
|
Electrotechnical Commission (IEC). This group is known as
|
|
@uref{http://www.nag.co.uk/sc22wg5/, WG5}.
|
|
|
|
The GNU Fortran compiler supports several of the new features of Fortran 2008;
|
|
the @uref{https://gcc.gnu.org/wiki/Fortran2008Status, wiki} has some information
|
|
about the current Fortran 2008 implementation status. In particular, the
|
|
following is implemented.
|
|
|
|
@itemize
|
|
@item The @option{-std=f2008} option and support for the file extensions
|
|
@file{.f08} and @file{.F08}.
|
|
|
|
@item The @code{OPEN} statement now supports the @code{NEWUNIT=} option,
|
|
which returns a unique file unit, thus preventing inadvertent use of the
|
|
same unit in different parts of the program.
|
|
|
|
@item The @code{g0} format descriptor and unlimited format items.
|
|
|
|
@item The mathematical intrinsics @code{ASINH}, @code{ACOSH}, @code{ATANH},
|
|
@code{ERF}, @code{ERFC}, @code{GAMMA}, @code{LOG_GAMMA}, @code{BESSEL_J0},
|
|
@code{BESSEL_J1}, @code{BESSEL_JN}, @code{BESSEL_Y0}, @code{BESSEL_Y1},
|
|
@code{BESSEL_YN}, @code{HYPOT}, @code{NORM2}, and @code{ERFC_SCALED}.
|
|
|
|
@item Using complex arguments with @code{TAN}, @code{SINH}, @code{COSH},
|
|
@code{TANH}, @code{ASIN}, @code{ACOS}, and @code{ATAN} is now possible;
|
|
@code{ATAN}(@var{Y},@var{X}) is now an alias for @code{ATAN2}(@var{Y},@var{X}).
|
|
|
|
@item Support of the @code{PARITY} intrinsic functions.
|
|
|
|
@item The following bit intrinsics: @code{LEADZ} and @code{TRAILZ} for
|
|
counting the number of leading and trailing zero bits, @code{POPCNT} and
|
|
@code{POPPAR} for counting the number of one bits and returning the parity;
|
|
@code{BGE}, @code{BGT}, @code{BLE}, and @code{BLT} for bitwise comparisons;
|
|
@code{DSHIFTL} and @code{DSHIFTR} for combined left and right shifts,
|
|
@code{MASKL} and @code{MASKR} for simple left and right justified masks,
|
|
@code{MERGE_BITS} for a bitwise merge using a mask, @code{SHIFTA},
|
|
@code{SHIFTL} and @code{SHIFTR} for shift operations, and the
|
|
transformational bit intrinsics @code{IALL}, @code{IANY} and @code{IPARITY}.
|
|
|
|
@item Support of the @code{EXECUTE_COMMAND_LINE} intrinsic subroutine.
|
|
|
|
@item Support for the @code{STORAGE_SIZE} intrinsic inquiry function.
|
|
|
|
@item The @code{INT@{8,16,32@}} and @code{REAL@{32,64,128@}} kind type
|
|
parameters and the array-valued named constants @code{INTEGER_KINDS},
|
|
@code{LOGICAL_KINDS}, @code{REAL_KINDS} and @code{CHARACTER_KINDS} of
|
|
the intrinsic module @code{ISO_FORTRAN_ENV}.
|
|
|
|
@item The module procedures @code{C_SIZEOF} of the intrinsic module
|
|
@code{ISO_C_BINDINGS} and @code{COMPILER_VERSION} and @code{COMPILER_OPTIONS}
|
|
of @code{ISO_FORTRAN_ENV}.
|
|
|
|
@item Coarray support for serial programs with @option{-fcoarray=single} flag
|
|
and experimental support for multiple images with the @option{-fcoarray=lib}
|
|
flag.
|
|
|
|
@item Submodules are supported. It should noted that @code{MODULEs} do not
|
|
produce the smod file needed by the descendent @code{SUBMODULEs} unless they
|
|
contain at least one @code{MODULE PROCEDURE} interface. The reason for this is
|
|
that @code{SUBMODULEs} are useless without @code{MODULE PROCEDUREs}. See
|
|
http://j3-fortran.org/doc/meeting/207/15-209.txt for a discussion and a draft
|
|
interpretation. Adopting this interpretation has the advantage that code that
|
|
does not use submodules does not generate smod files.
|
|
|
|
@item The @code{DO CONCURRENT} construct is supported.
|
|
|
|
@item The @code{BLOCK} construct is supported.
|
|
|
|
@item The @code{STOP} and the new @code{ERROR STOP} statements now
|
|
support all constant expressions. Both show the signals which were signaling
|
|
at termination.
|
|
|
|
@item Support for the @code{CONTIGUOUS} attribute.
|
|
|
|
@item Support for @code{ALLOCATE} with @code{MOLD}.
|
|
|
|
@item Support for the @code{IMPURE} attribute for procedures, which
|
|
allows for @code{ELEMENTAL} procedures without the restrictions of
|
|
@code{PURE}.
|
|
|
|
@item Null pointers (including @code{NULL()}) and not-allocated variables
|
|
can be used as actual argument to optional non-pointer, non-allocatable
|
|
dummy arguments, denoting an absent argument.
|
|
|
|
@item Non-pointer variables with @code{TARGET} attribute can be used as
|
|
actual argument to @code{POINTER} dummies with @code{INTENT(IN)}.
|
|
|
|
@item Pointers including procedure pointers and those in a derived
|
|
type (pointer components) can now be initialized by a target instead
|
|
of only by @code{NULL}.
|
|
|
|
@item The @code{EXIT} statement (with construct-name) can be now be
|
|
used to leave not only the @code{DO} but also the @code{ASSOCIATE},
|
|
@code{BLOCK}, @code{IF}, @code{SELECT CASE} and @code{SELECT TYPE}
|
|
constructs.
|
|
|
|
@item Internal procedures can now be used as actual argument.
|
|
|
|
@item Minor features: obsolesce diagnostics for @code{ENTRY} with
|
|
@option{-std=f2008}; a line may start with a semicolon; for internal
|
|
and module procedures @code{END} can be used instead of
|
|
@code{END SUBROUTINE} and @code{END FUNCTION}; @code{SELECTED_REAL_KIND}
|
|
now also takes a @code{RADIX} argument; intrinsic types are supported
|
|
for @code{TYPE}(@var{intrinsic-type-spec}); multiple type-bound procedures
|
|
can be declared in a single @code{PROCEDURE} statement; implied-shape
|
|
arrays are supported for named constants (@code{PARAMETER}).
|
|
@end itemize
|
|
|
|
|
|
|
|
@node TS 29113 status
|
|
@section Technical Specification 29113 Status
|
|
|
|
GNU Fortran supports some of the new features of the Technical
|
|
Specification (TS) 29113 on Further Interoperability of Fortran with C.
|
|
The @uref{https://gcc.gnu.org/wiki/TS29113Status, wiki} has some information
|
|
about the current TS 29113 implementation status. In particular, the
|
|
following is implemented.
|
|
|
|
See also @ref{Further Interoperability of Fortran with C}.
|
|
|
|
@itemize
|
|
@item The @option{-std=f2008ts} option.
|
|
|
|
@item The @code{OPTIONAL} attribute is allowed for dummy arguments
|
|
of @code{BIND(C) procedures.}
|
|
|
|
@item The @code{RANK} intrinsic is supported.
|
|
|
|
@item GNU Fortran's implementation for variables with @code{ASYNCHRONOUS}
|
|
attribute is compatible with TS 29113.
|
|
|
|
@item Assumed types (@code{TYPE(*)}.
|
|
|
|
@item Assumed-rank (@code{DIMENSION(..)}). However, the array descriptor
|
|
of the TS is not yet supported.
|
|
@end itemize
|
|
|
|
|
|
@node TS 18508 status
|
|
@section Technical Specification 18508 Status
|
|
|
|
GNU Fortran supports the following new features of the Technical
|
|
Specification 18508 on Additional Parallel Features in Fortran:
|
|
|
|
@itemize
|
|
@item The new atomic ADD, CAS, FETCH and ADD/OR/XOR, OR and XOR intrinsics.
|
|
|
|
@item The @code{CO_MIN} and @code{CO_MAX} and @code{SUM} reduction intrinsics.
|
|
And the @code{CO_BROADCAST} and @code{CO_REDUCE} intrinsic, except that those
|
|
do not support polymorphic types or types with allocatable, pointer or
|
|
polymorphic components.
|
|
|
|
@item Events (@code{EVENT POST}, @code{EVENT WAIT}, @code{EVENT_QUERY})
|
|
@end itemize
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Compiler Characteristics
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Compiler Characteristics
|
|
@chapter Compiler Characteristics
|
|
|
|
This chapter describes certain characteristics of the GNU Fortran
|
|
compiler, that are not specified by the Fortran standard, but which
|
|
might in some way or another become visible to the programmer.
|
|
|
|
@menu
|
|
* KIND Type Parameters::
|
|
* Internal representation of LOGICAL variables::
|
|
* Thread-safety of the runtime library::
|
|
* Data consistency and durability::
|
|
* Files opened without an explicit ACTION= specifier::
|
|
* File operations on symbolic links::
|
|
@end menu
|
|
|
|
|
|
@node KIND Type Parameters
|
|
@section KIND Type Parameters
|
|
@cindex kind
|
|
|
|
The @code{KIND} type parameters supported by GNU Fortran for the primitive
|
|
data types are:
|
|
|
|
@table @code
|
|
|
|
@item INTEGER
|
|
1, 2, 4, 8*, 16*, default: 4**
|
|
|
|
@item LOGICAL
|
|
1, 2, 4, 8*, 16*, default: 4**
|
|
|
|
@item REAL
|
|
4, 8, 10*, 16*, default: 4***
|
|
|
|
@item COMPLEX
|
|
4, 8, 10*, 16*, default: 4***
|
|
|
|
@item DOUBLE PRECISION
|
|
4, 8, 10*, 16*, default: 8***
|
|
|
|
@item CHARACTER
|
|
1, 4, default: 1
|
|
|
|
@end table
|
|
|
|
@noindent
|
|
* not available on all systems @*
|
|
** unless @option{-fdefault-integer-8} is used @*
|
|
*** unless @option{-fdefault-real-8} is used (see @ref{Fortran Dialect Options})
|
|
|
|
@noindent
|
|
The @code{KIND} value matches the storage size in bytes, except for
|
|
@code{COMPLEX} where the storage size is twice as much (or both real and
|
|
imaginary part are a real value of the given size). It is recommended to use
|
|
the @ref{SELECTED_CHAR_KIND}, @ref{SELECTED_INT_KIND} and
|
|
@ref{SELECTED_REAL_KIND} intrinsics or the @code{INT8}, @code{INT16},
|
|
@code{INT32}, @code{INT64}, @code{REAL32}, @code{REAL64}, and @code{REAL128}
|
|
parameters of the @code{ISO_FORTRAN_ENV} module instead of the concrete values.
|
|
The available kind parameters can be found in the constant arrays
|
|
@code{CHARACTER_KINDS}, @code{INTEGER_KINDS}, @code{LOGICAL_KINDS} and
|
|
@code{REAL_KINDS} in the @ref{ISO_FORTRAN_ENV} module. For C interoperability,
|
|
the kind parameters of the @ref{ISO_C_BINDING} module should be used.
|
|
|
|
|
|
@node Internal representation of LOGICAL variables
|
|
@section Internal representation of LOGICAL variables
|
|
@cindex logical, variable representation
|
|
|
|
The Fortran standard does not specify how variables of @code{LOGICAL}
|
|
type are represented, beyond requiring that @code{LOGICAL} variables
|
|
of default kind have the same storage size as default @code{INTEGER}
|
|
and @code{REAL} variables. The GNU Fortran internal representation is
|
|
as follows.
|
|
|
|
A @code{LOGICAL(KIND=N)} variable is represented as an
|
|
@code{INTEGER(KIND=N)} variable, however, with only two permissible
|
|
values: @code{1} for @code{.TRUE.} and @code{0} for
|
|
@code{.FALSE.}. Any other integer value results in undefined behavior.
|
|
|
|
See also @ref{Argument passing conventions} and @ref{Interoperability with C}.
|
|
|
|
|
|
@node Thread-safety of the runtime library
|
|
@section Thread-safety of the runtime library
|
|
@cindex thread-safety, threads
|
|
|
|
GNU Fortran can be used in programs with multiple threads, e.g.@: by
|
|
using OpenMP, by calling OS thread handling functions via the
|
|
@code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code
|
|
being called from a multi-threaded program.
|
|
|
|
The GNU Fortran runtime library, (@code{libgfortran}), supports being
|
|
called concurrently from multiple threads with the following
|
|
exceptions.
|
|
|
|
During library initialization, the C @code{getenv} function is used,
|
|
which need not be thread-safe. Similarly, the @code{getenv}
|
|
function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and
|
|
@code{GETENV} intrinsics. It is the responsibility of the user to
|
|
ensure that the environment is not being updated concurrently when any
|
|
of these actions are taking place.
|
|
|
|
The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are
|
|
implemented with the @code{system} function, which need not be
|
|
thread-safe. It is the responsibility of the user to ensure that
|
|
@code{system} is not called concurrently.
|
|
|
|
For platforms not supporting thread-safe POSIX functions, further
|
|
functionality might not be thread-safe. For details, please consult
|
|
the documentation for your operating system.
|
|
|
|
The GNU Fortran runtime library uses various C library functions that
|
|
depend on the locale, such as @code{strtod} and @code{snprintf}. In
|
|
order to work correctly in locale-aware programs that set the locale
|
|
using @code{setlocale}, the locale is reset to the default ``C''
|
|
locale while executing a formatted @code{READ} or @code{WRITE}
|
|
statement. On targets supporting the POSIX 2008 per-thread locale
|
|
functions (e.g. @code{newlocale}, @code{uselocale},
|
|
@code{freelocale}), these are used and thus the global locale set
|
|
using @code{setlocale} or the per-thread locales in other threads are
|
|
not affected. However, on targets lacking this functionality, the
|
|
global LC_NUMERIC locale is set to ``C'' during the formatted I/O.
|
|
Thus, on such targets it's not safe to call @code{setlocale}
|
|
concurrently from another thread while a Fortran formatted I/O
|
|
operation is in progress. Also, other threads doing something
|
|
dependent on the LC_NUMERIC locale might not work correctly if a
|
|
formatted I/O operation is in progress in another thread.
|
|
|
|
@node Data consistency and durability
|
|
@section Data consistency and durability
|
|
@cindex consistency, durability
|
|
|
|
This section contains a brief overview of data and metadata
|
|
consistency and durability issues when doing I/O.
|
|
|
|
With respect to durability, GNU Fortran makes no effort to ensure that
|
|
data is committed to stable storage. If this is required, the GNU
|
|
Fortran programmer can use the intrinsic @code{FNUM} to retrieve the
|
|
low level file descriptor corresponding to an open Fortran unit. Then,
|
|
using e.g. the @code{ISO_C_BINDING} feature, one can call the
|
|
underlying system call to flush dirty data to stable storage, such as
|
|
@code{fsync} on POSIX, @code{_commit} on MingW, or @code{fcntl(fd,
|
|
F_FULLSYNC, 0)} on Mac OS X. The following example shows how to call
|
|
fsync:
|
|
|
|
@smallexample
|
|
! Declare the interface for POSIX fsync function
|
|
interface
|
|
function fsync (fd) bind(c,name="fsync")
|
|
use iso_c_binding, only: c_int
|
|
integer(c_int), value :: fd
|
|
integer(c_int) :: fsync
|
|
end function fsync
|
|
end interface
|
|
|
|
! Variable declaration
|
|
integer :: ret
|
|
|
|
! Opening unit 10
|
|
open (10,file="foo")
|
|
|
|
! ...
|
|
! Perform I/O on unit 10
|
|
! ...
|
|
|
|
! Flush and sync
|
|
flush(10)
|
|
ret = fsync(fnum(10))
|
|
|
|
! Handle possible error
|
|
if (ret /= 0) stop "Error calling FSYNC"
|
|
@end smallexample
|
|
|
|
With respect to consistency, for regular files GNU Fortran uses
|
|
buffered I/O in order to improve performance. This buffer is flushed
|
|
automatically when full and in some other situations, e.g. when
|
|
closing a unit. It can also be explicitly flushed with the
|
|
@code{FLUSH} statement. Also, the buffering can be turned off with the
|
|
@code{GFORTRAN_UNBUFFERED_ALL} and
|
|
@code{GFORTRAN_UNBUFFERED_PRECONNECTED} environment variables. Special
|
|
files, such as terminals and pipes, are always unbuffered. Sometimes,
|
|
however, further things may need to be done in order to allow other
|
|
processes to see data that GNU Fortran has written, as follows.
|
|
|
|
The Windows platform supports a relaxed metadata consistency model,
|
|
where file metadata is written to the directory lazily. This means
|
|
that, for instance, the @code{dir} command can show a stale size for a
|
|
file. One can force a directory metadata update by closing the unit,
|
|
or by calling @code{_commit} on the file descriptor. Note, though,
|
|
that @code{_commit} will force all dirty data to stable storage, which
|
|
is often a very slow operation.
|
|
|
|
The Network File System (NFS) implements a relaxed consistency model
|
|
called open-to-close consistency. Closing a file forces dirty data and
|
|
metadata to be flushed to the server, and opening a file forces the
|
|
client to contact the server in order to revalidate cached
|
|
data. @code{fsync} will also force a flush of dirty data and metadata
|
|
to the server. Similar to @code{open} and @code{close}, acquiring and
|
|
releasing @code{fcntl} file locks, if the server supports them, will
|
|
also force cache validation and flushing dirty data and metadata.
|
|
|
|
|
|
@node Files opened without an explicit ACTION= specifier
|
|
@section Files opened without an explicit ACTION= specifier
|
|
@cindex open, action
|
|
|
|
The Fortran standard says that if an @code{OPEN} statement is executed
|
|
without an explicit @code{ACTION=} specifier, the default value is
|
|
processor dependent. GNU Fortran behaves as follows:
|
|
|
|
@enumerate
|
|
@item Attempt to open the file with @code{ACTION='READWRITE'}
|
|
@item If that fails, try to open with @code{ACTION='READ'}
|
|
@item If that fails, try to open with @code{ACTION='WRITE'}
|
|
@item If that fails, generate an error
|
|
@end enumerate
|
|
|
|
|
|
@node File operations on symbolic links
|
|
@section File operations on symbolic links
|
|
@cindex file, symbolic link
|
|
|
|
This section documents the behavior of GNU Fortran for file operations on
|
|
symbolic links, on systems that support them.
|
|
|
|
@itemize
|
|
|
|
@item Results of INQUIRE statements of the ``inquire by file'' form will
|
|
relate to the target of the symbolic link. For example,
|
|
@code{INQUIRE(FILE="foo",EXIST=ex)} will set @var{ex} to @var{.true.} if
|
|
@var{foo} is a symbolic link pointing to an existing file, and @var{.false.}
|
|
if @var{foo} points to an non-existing file (``dangling'' symbolic link).
|
|
|
|
@item Using the @code{OPEN} statement with a @code{STATUS="NEW"} specifier
|
|
on a symbolic link will result in an error condition, whether the symbolic
|
|
link points to an existing target or is dangling.
|
|
|
|
@item If a symbolic link was connected, using the @code{CLOSE} statement
|
|
with a @code{STATUS="DELETE"} specifier will cause the symbolic link itself
|
|
to be deleted, not its target.
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Extensions
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@c Maybe this chapter should be merged with the 'Standards' section,
|
|
@c whenever that is written :-)
|
|
|
|
@node Extensions
|
|
@chapter Extensions
|
|
@cindex extensions
|
|
|
|
The two sections below detail the extensions to standard Fortran that are
|
|
implemented in GNU Fortran, as well as some of the popular or
|
|
historically important extensions that are not (or not yet) implemented.
|
|
For the latter case, we explain the alternatives available to GNU Fortran
|
|
users, including replacement by standard-conforming code or GNU
|
|
extensions.
|
|
|
|
@menu
|
|
* Extensions implemented in GNU Fortran::
|
|
* Extensions not implemented in GNU Fortran::
|
|
@end menu
|
|
|
|
|
|
@node Extensions implemented in GNU Fortran
|
|
@section Extensions implemented in GNU Fortran
|
|
@cindex extensions, implemented
|
|
|
|
GNU Fortran implements a number of extensions over standard
|
|
Fortran. This chapter contains information on their syntax and
|
|
meaning. There are currently two categories of GNU Fortran
|
|
extensions, those that provide functionality beyond that provided
|
|
by any standard, and those that are supported by GNU Fortran
|
|
purely for backward compatibility with legacy compilers. By default,
|
|
@option{-std=gnu} allows the compiler to accept both types of
|
|
extensions, but to warn about the use of the latter. Specifying
|
|
either @option{-std=f95}, @option{-std=f2003} or @option{-std=f2008}
|
|
disables both types of extensions, and @option{-std=legacy} allows both
|
|
without warning. The special compile flag @option{-fdec} enables additional
|
|
compatibility extensions along with those enabled by @option{-std=legacy}.
|
|
|
|
@menu
|
|
* Old-style kind specifications::
|
|
* Old-style variable initialization::
|
|
* Extensions to namelist::
|
|
* X format descriptor without count field::
|
|
* Commas in FORMAT specifications::
|
|
* Missing period in FORMAT specifications::
|
|
* I/O item lists::
|
|
* @code{Q} exponent-letter::
|
|
* BOZ literal constants::
|
|
* Real array indices::
|
|
* Unary operators::
|
|
* Implicitly convert LOGICAL and INTEGER values::
|
|
* Hollerith constants support::
|
|
* Cray pointers::
|
|
* CONVERT specifier::
|
|
* OpenMP::
|
|
* OpenACC::
|
|
* Argument list functions::
|
|
* Read/Write after EOF marker::
|
|
* STRUCTURE and RECORD::
|
|
* UNION and MAP::
|
|
* Type variants for integer intrinsics::
|
|
* AUTOMATIC and STATIC attributes::
|
|
* Extended math intrinsics::
|
|
* Form feed as whitespace::
|
|
* TYPE as an alias for PRINT::
|
|
* %LOC as an rvalue::
|
|
* .XOR. operator::
|
|
* Bitwise logical operators::
|
|
* Extended I/O specifiers::
|
|
* Legacy PARAMETER statements::
|
|
* Default exponents::
|
|
@end menu
|
|
|
|
@node Old-style kind specifications
|
|
@subsection Old-style kind specifications
|
|
@cindex kind, old-style
|
|
|
|
GNU Fortran allows old-style kind specifications in declarations. These
|
|
look like:
|
|
@smallexample
|
|
TYPESPEC*size x,y,z
|
|
@end smallexample
|
|
@noindent
|
|
where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
|
|
etc.), and where @code{size} is a byte count corresponding to the
|
|
storage size of a valid kind for that type. (For @code{COMPLEX}
|
|
variables, @code{size} is the total size of the real and imaginary
|
|
parts.) The statement then declares @code{x}, @code{y} and @code{z} to
|
|
be of type @code{TYPESPEC} with the appropriate kind. This is
|
|
equivalent to the standard-conforming declaration
|
|
@smallexample
|
|
TYPESPEC(k) x,y,z
|
|
@end smallexample
|
|
@noindent
|
|
where @code{k} is the kind parameter suitable for the intended precision. As
|
|
kind parameters are implementation-dependent, use the @code{KIND},
|
|
@code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve
|
|
the correct value, for instance @code{REAL*8 x} can be replaced by:
|
|
@smallexample
|
|
INTEGER, PARAMETER :: dbl = KIND(1.0d0)
|
|
REAL(KIND=dbl) :: x
|
|
@end smallexample
|
|
|
|
@node Old-style variable initialization
|
|
@subsection Old-style variable initialization
|
|
|
|
GNU Fortran allows old-style initialization of variables of the
|
|
form:
|
|
@smallexample
|
|
INTEGER i/1/,j/2/
|
|
REAL x(2,2) /3*0.,1./
|
|
@end smallexample
|
|
The syntax for the initializers is as for the @code{DATA} statement, but
|
|
unlike in a @code{DATA} statement, an initializer only applies to the
|
|
variable immediately preceding the initialization. In other words,
|
|
something like @code{INTEGER I,J/2,3/} is not valid. This style of
|
|
initialization is only allowed in declarations without double colons
|
|
(@code{::}); the double colons were introduced in Fortran 90, which also
|
|
introduced a standard syntax for initializing variables in type
|
|
declarations.
|
|
|
|
Examples of standard-conforming code equivalent to the above example
|
|
are:
|
|
@smallexample
|
|
! Fortran 90
|
|
INTEGER :: i = 1, j = 2
|
|
REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
|
|
! Fortran 77
|
|
INTEGER i, j
|
|
REAL x(2,2)
|
|
DATA i/1/, j/2/, x/3*0.,1./
|
|
@end smallexample
|
|
|
|
Note that variables which are explicitly initialized in declarations
|
|
or in @code{DATA} statements automatically acquire the @code{SAVE}
|
|
attribute.
|
|
|
|
@node Extensions to namelist
|
|
@subsection Extensions to namelist
|
|
@cindex Namelist
|
|
|
|
GNU Fortran fully supports the Fortran 95 standard for namelist I/O
|
|
including array qualifiers, substrings and fully qualified derived types.
|
|
The output from a namelist write is compatible with namelist read. The
|
|
output has all names in upper case and indentation to column 1 after the
|
|
namelist name. Two extensions are permitted:
|
|
|
|
Old-style use of @samp{$} instead of @samp{&}
|
|
@smallexample
|
|
$MYNML
|
|
X(:)%Y(2) = 1.0 2.0 3.0
|
|
CH(1:4) = "abcd"
|
|
$END
|
|
@end smallexample
|
|
|
|
It should be noted that the default terminator is @samp{/} rather than
|
|
@samp{&END}.
|
|
|
|
Querying of the namelist when inputting from stdin. After at least
|
|
one space, entering @samp{?} sends to stdout the namelist name and the names of
|
|
the variables in the namelist:
|
|
@smallexample
|
|
?
|
|
|
|
&mynml
|
|
x
|
|
x%y
|
|
ch
|
|
&end
|
|
@end smallexample
|
|
|
|
Entering @samp{=?} outputs the namelist to stdout, as if
|
|
@code{WRITE(*,NML = mynml)} had been called:
|
|
@smallexample
|
|
=?
|
|
|
|
&MYNML
|
|
X(1)%Y= 0.000000 , 1.000000 , 0.000000 ,
|
|
X(2)%Y= 0.000000 , 2.000000 , 0.000000 ,
|
|
X(3)%Y= 0.000000 , 3.000000 , 0.000000 ,
|
|
CH=abcd, /
|
|
@end smallexample
|
|
|
|
To aid this dialog, when input is from stdin, errors send their
|
|
messages to stderr and execution continues, even if @code{IOSTAT} is set.
|
|
|
|
@code{PRINT} namelist is permitted. This causes an error if
|
|
@option{-std=f95} is used.
|
|
@smallexample
|
|
PROGRAM test_print
|
|
REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/)
|
|
NAMELIST /mynml/ x
|
|
PRINT mynml
|
|
END PROGRAM test_print
|
|
@end smallexample
|
|
|
|
Expanded namelist reads are permitted. This causes an error if
|
|
@option{-std=f95} is used. In the following example, the first element
|
|
of the array will be given the value 0.00 and the two succeeding
|
|
elements will be given the values 1.00 and 2.00.
|
|
@smallexample
|
|
&MYNML
|
|
X(1,1) = 0.00 , 1.00 , 2.00
|
|
/
|
|
@end smallexample
|
|
|
|
When writing a namelist, if no @code{DELIM=} is specified, by default a
|
|
double quote is used to delimit character strings. If -std=F95, F2003,
|
|
or F2008, etc, the delim status is set to 'none'. Defaulting to
|
|
quotes ensures that namelists with character strings can be subsequently
|
|
read back in accurately.
|
|
|
|
@node X format descriptor without count field
|
|
@subsection @code{X} format descriptor without count field
|
|
|
|
To support legacy codes, GNU Fortran permits the count field of the
|
|
@code{X} edit descriptor in @code{FORMAT} statements to be omitted.
|
|
When omitted, the count is implicitly assumed to be one.
|
|
|
|
@smallexample
|
|
PRINT 10, 2, 3
|
|
10 FORMAT (I1, X, I1)
|
|
@end smallexample
|
|
|
|
@node Commas in FORMAT specifications
|
|
@subsection Commas in @code{FORMAT} specifications
|
|
|
|
To support legacy codes, GNU Fortran allows the comma separator
|
|
to be omitted immediately before and after character string edit
|
|
descriptors in @code{FORMAT} statements.
|
|
|
|
@smallexample
|
|
PRINT 10, 2, 3
|
|
10 FORMAT ('FOO='I1' BAR='I2)
|
|
@end smallexample
|
|
|
|
|
|
@node Missing period in FORMAT specifications
|
|
@subsection Missing period in @code{FORMAT} specifications
|
|
|
|
To support legacy codes, GNU Fortran allows missing periods in format
|
|
specifications if and only if @option{-std=legacy} is given on the
|
|
command line. This is considered non-conforming code and is
|
|
discouraged.
|
|
|
|
@smallexample
|
|
REAL :: value
|
|
READ(*,10) value
|
|
10 FORMAT ('F4')
|
|
@end smallexample
|
|
|
|
@node I/O item lists
|
|
@subsection I/O item lists
|
|
@cindex I/O item lists
|
|
|
|
To support legacy codes, GNU Fortran allows the input item list
|
|
of the @code{READ} statement, and the output item lists of the
|
|
@code{WRITE} and @code{PRINT} statements, to start with a comma.
|
|
|
|
@node @code{Q} exponent-letter
|
|
@subsection @code{Q} exponent-letter
|
|
@cindex @code{Q} exponent-letter
|
|
|
|
GNU Fortran accepts real literal constants with an exponent-letter
|
|
of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted
|
|
as a @code{REAL(16)} entity on targets that support this type. If
|
|
the target does not support @code{REAL(16)} but has a @code{REAL(10)}
|
|
type, then the real-literal-constant will be interpreted as a
|
|
@code{REAL(10)} entity. In the absence of @code{REAL(16)} and
|
|
@code{REAL(10)}, an error will occur.
|
|
|
|
@node BOZ literal constants
|
|
@subsection BOZ literal constants
|
|
@cindex BOZ literal constants
|
|
|
|
Besides decimal constants, Fortran also supports binary (@code{b}),
|
|
octal (@code{o}) and hexadecimal (@code{z}) integer constants. The
|
|
syntax is: @samp{prefix quote digits quote}, were the prefix is
|
|
either @code{b}, @code{o} or @code{z}, quote is either @code{'} or
|
|
@code{"} and the digits are for binary @code{0} or @code{1}, for
|
|
octal between @code{0} and @code{7}, and for hexadecimal between
|
|
@code{0} and @code{F}. (Example: @code{b'01011101'}.)
|
|
|
|
Up to Fortran 95, BOZ literals were only allowed to initialize
|
|
integer variables in DATA statements. Since Fortran 2003 BOZ literals
|
|
are also allowed as argument of @code{REAL}, @code{DBLE}, @code{INT}
|
|
and @code{CMPLX}; the result is the same as if the integer BOZ
|
|
literal had been converted by @code{TRANSFER} to, respectively,
|
|
@code{real}, @code{double precision}, @code{integer} or @code{complex}.
|
|
As GNU Fortran extension the intrinsic procedures @code{FLOAT},
|
|
@code{DFLOAT}, @code{COMPLEX} and @code{DCMPLX} are treated alike.
|
|
|
|
As an extension, GNU Fortran allows hexadecimal BOZ literal constants to
|
|
be specified using the @code{X} prefix, in addition to the standard
|
|
@code{Z} prefix. The BOZ literal can also be specified by adding a
|
|
suffix to the string, for example, @code{Z'ABC'} and @code{'ABC'Z} are
|
|
equivalent.
|
|
|
|
Furthermore, GNU Fortran allows using BOZ literal constants outside
|
|
DATA statements and the four intrinsic functions allowed by Fortran 2003.
|
|
In DATA statements, in direct assignments, where the right-hand side
|
|
only contains a BOZ literal constant, and for old-style initializers of
|
|
the form @code{integer i /o'0173'/}, the constant is transferred
|
|
as if @code{TRANSFER} had been used; for @code{COMPLEX} numbers, only
|
|
the real part is initialized unless @code{CMPLX} is used. In all other
|
|
cases, the BOZ literal constant is converted to an @code{INTEGER} value with
|
|
the largest decimal representation. This value is then converted
|
|
numerically to the type and kind of the variable in question.
|
|
(For instance, @code{real :: r = b'0000001' + 1} initializes @code{r}
|
|
with @code{2.0}.) As different compilers implement the extension
|
|
differently, one should be careful when doing bitwise initialization
|
|
of non-integer variables.
|
|
|
|
Note that initializing an @code{INTEGER} variable with a statement such
|
|
as @code{DATA i/Z'FFFFFFFF'/} will give an integer overflow error rather
|
|
than the desired result of @math{-1} when @code{i} is a 32-bit integer
|
|
on a system that supports 64-bit integers. The @samp{-fno-range-check}
|
|
option can be used as a workaround for legacy code that initializes
|
|
integers in this manner.
|
|
|
|
@node Real array indices
|
|
@subsection Real array indices
|
|
@cindex array, indices of type real
|
|
|
|
As an extension, GNU Fortran allows the use of @code{REAL} expressions
|
|
or variables as array indices.
|
|
|
|
@node Unary operators
|
|
@subsection Unary operators
|
|
@cindex operators, unary
|
|
|
|
As an extension, GNU Fortran allows unary plus and unary minus operators
|
|
to appear as the second operand of binary arithmetic operators without
|
|
the need for parenthesis.
|
|
|
|
@smallexample
|
|
X = Y * -Z
|
|
@end smallexample
|
|
|
|
@node Implicitly convert LOGICAL and INTEGER values
|
|
@subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values
|
|
@cindex conversion, to integer
|
|
@cindex conversion, to logical
|
|
|
|
As an extension for backwards compatibility with other compilers, GNU
|
|
Fortran allows the implicit conversion of @code{LOGICAL} values to
|
|
@code{INTEGER} values and vice versa. When converting from a
|
|
@code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as
|
|
zero, and @code{.TRUE.} is interpreted as one. When converting from
|
|
@code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as
|
|
@code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}.
|
|
|
|
@smallexample
|
|
LOGICAL :: l
|
|
l = 1
|
|
@end smallexample
|
|
@smallexample
|
|
INTEGER :: i
|
|
i = .TRUE.
|
|
@end smallexample
|
|
|
|
However, there is no implicit conversion of @code{INTEGER} values in
|
|
@code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values
|
|
in I/O operations.
|
|
|
|
@node Hollerith constants support
|
|
@subsection Hollerith constants support
|
|
@cindex Hollerith constants
|
|
|
|
GNU Fortran supports Hollerith constants in assignments, function
|
|
arguments, and @code{DATA} and @code{ASSIGN} statements. A Hollerith
|
|
constant is written as a string of characters preceded by an integer
|
|
constant indicating the character count, and the letter @code{H} or
|
|
@code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER},
|
|
@code{REAL}, or @code{complex}) or @code{LOGICAL} variable. The
|
|
constant will be padded or truncated to fit the size of the variable in
|
|
which it is stored.
|
|
|
|
Examples of valid uses of Hollerith constants:
|
|
@smallexample
|
|
complex*16 x(2)
|
|
data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/
|
|
x(1) = 16HABCDEFGHIJKLMNOP
|
|
call foo (4h abc)
|
|
@end smallexample
|
|
|
|
Invalid Hollerith constants examples:
|
|
@smallexample
|
|
integer*4 a
|
|
a = 8H12345678 ! Valid, but the Hollerith constant will be truncated.
|
|
a = 0H ! At least one character is needed.
|
|
@end smallexample
|
|
|
|
In general, Hollerith constants were used to provide a rudimentary
|
|
facility for handling character strings in early Fortran compilers,
|
|
prior to the introduction of @code{CHARACTER} variables in Fortran 77;
|
|
in those cases, the standard-compliant equivalent is to convert the
|
|
program to use proper character strings. On occasion, there may be a
|
|
case where the intent is specifically to initialize a numeric variable
|
|
with a given byte sequence. In these cases, the same result can be
|
|
obtained by using the @code{TRANSFER} statement, as in this example.
|
|
@smallexample
|
|
INTEGER(KIND=4) :: a
|
|
a = TRANSFER ("abcd", a) ! equivalent to: a = 4Habcd
|
|
@end smallexample
|
|
|
|
|
|
@node Cray pointers
|
|
@subsection Cray pointers
|
|
@cindex pointer, Cray
|
|
|
|
Cray pointers are part of a non-standard extension that provides a
|
|
C-like pointer in Fortran. This is accomplished through a pair of
|
|
variables: an integer "pointer" that holds a memory address, and a
|
|
"pointee" that is used to dereference the pointer.
|
|
|
|
Pointer/pointee pairs are declared in statements of the form:
|
|
@smallexample
|
|
pointer ( <pointer> , <pointee> )
|
|
@end smallexample
|
|
or,
|
|
@smallexample
|
|
pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ...
|
|
@end smallexample
|
|
The pointer is an integer that is intended to hold a memory address.
|
|
The pointee may be an array or scalar. A pointee can be an assumed
|
|
size array---that is, the last dimension may be left unspecified by
|
|
using a @code{*} in place of a value---but a pointee cannot be an
|
|
assumed shape array. No space is allocated for the pointee.
|
|
|
|
The pointee may have its type declared before or after the pointer
|
|
statement, and its array specification (if any) may be declared
|
|
before, during, or after the pointer statement. The pointer may be
|
|
declared as an integer prior to the pointer statement. However, some
|
|
machines have default integer sizes that are different than the size
|
|
of a pointer, and so the following code is not portable:
|
|
@smallexample
|
|
integer ipt
|
|
pointer (ipt, iarr)
|
|
@end smallexample
|
|
If a pointer is declared with a kind that is too small, the compiler
|
|
will issue a warning; the resulting binary will probably not work
|
|
correctly, because the memory addresses stored in the pointers may be
|
|
truncated. It is safer to omit the first line of the above example;
|
|
if explicit declaration of ipt's type is omitted, then the compiler
|
|
will ensure that ipt is an integer variable large enough to hold a
|
|
pointer.
|
|
|
|
Pointer arithmetic is valid with Cray pointers, but it is not the same
|
|
as C pointer arithmetic. Cray pointers are just ordinary integers, so
|
|
the user is responsible for determining how many bytes to add to a
|
|
pointer in order to increment it. Consider the following example:
|
|
@smallexample
|
|
real target(10)
|
|
real pointee(10)
|
|
pointer (ipt, pointee)
|
|
ipt = loc (target)
|
|
ipt = ipt + 1
|
|
@end smallexample
|
|
The last statement does not set @code{ipt} to the address of
|
|
@code{target(1)}, as it would in C pointer arithmetic. Adding @code{1}
|
|
to @code{ipt} just adds one byte to the address stored in @code{ipt}.
|
|
|
|
Any expression involving the pointee will be translated to use the
|
|
value stored in the pointer as the base address.
|
|
|
|
To get the address of elements, this extension provides an intrinsic
|
|
function @code{LOC()}. The @code{LOC()} function is equivalent to the
|
|
@code{&} operator in C, except the address is cast to an integer type:
|
|
@smallexample
|
|
real ar(10)
|
|
pointer(ipt, arpte(10))
|
|
real arpte
|
|
ipt = loc(ar) ! Makes arpte is an alias for ar
|
|
arpte(1) = 1.0 ! Sets ar(1) to 1.0
|
|
@end smallexample
|
|
The pointer can also be set by a call to the @code{MALLOC} intrinsic
|
|
(see @ref{MALLOC}).
|
|
|
|
Cray pointees often are used to alias an existing variable. For
|
|
example:
|
|
@smallexample
|
|
integer target(10)
|
|
integer iarr(10)
|
|
pointer (ipt, iarr)
|
|
ipt = loc(target)
|
|
@end smallexample
|
|
As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for
|
|
@code{target}. The optimizer, however, will not detect this aliasing, so
|
|
it is unsafe to use @code{iarr} and @code{target} simultaneously. Using
|
|
a pointee in any way that violates the Fortran aliasing rules or
|
|
assumptions is illegal. It is the user's responsibility to avoid doing
|
|
this; the compiler works under the assumption that no such aliasing
|
|
occurs.
|
|
|
|
Cray pointers will work correctly when there is no aliasing (i.e., when
|
|
they are used to access a dynamically allocated block of memory), and
|
|
also in any routine where a pointee is used, but any variable with which
|
|
it shares storage is not used. Code that violates these rules may not
|
|
run as the user intends. This is not a bug in the optimizer; any code
|
|
that violates the aliasing rules is illegal. (Note that this is not
|
|
unique to GNU Fortran; any Fortran compiler that supports Cray pointers
|
|
will ``incorrectly'' optimize code with illegal aliasing.)
|
|
|
|
There are a number of restrictions on the attributes that can be applied
|
|
to Cray pointers and pointees. Pointees may not have the
|
|
@code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY},
|
|
@code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers
|
|
may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET},
|
|
@code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor
|
|
may they be function results. Pointees may not occur in more than one
|
|
pointer statement. A pointee cannot be a pointer. Pointees cannot occur
|
|
in equivalence, common, or data statements.
|
|
|
|
A Cray pointer may also point to a function or a subroutine. For
|
|
example, the following excerpt is valid:
|
|
@smallexample
|
|
implicit none
|
|
external sub
|
|
pointer (subptr,subpte)
|
|
external subpte
|
|
subptr = loc(sub)
|
|
call subpte()
|
|
[...]
|
|
subroutine sub
|
|
[...]
|
|
end subroutine sub
|
|
@end smallexample
|
|
|
|
A pointer may be modified during the course of a program, and this
|
|
will change the location to which the pointee refers. However, when
|
|
pointees are passed as arguments, they are treated as ordinary
|
|
variables in the invoked function. Subsequent changes to the pointer
|
|
will not change the base address of the array that was passed.
|
|
|
|
@node CONVERT specifier
|
|
@subsection @code{CONVERT} specifier
|
|
@cindex @code{CONVERT} specifier
|
|
|
|
GNU Fortran allows the conversion of unformatted data between little-
|
|
and big-endian representation to facilitate moving of data
|
|
between different systems. The conversion can be indicated with
|
|
the @code{CONVERT} specifier on the @code{OPEN} statement.
|
|
@xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying
|
|
the data format via an environment variable.
|
|
|
|
Valid values for @code{CONVERT} are:
|
|
@itemize @w{}
|
|
@item @code{CONVERT='NATIVE'} Use the native format. This is the default.
|
|
@item @code{CONVERT='SWAP'} Swap between little- and big-endian.
|
|
@item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation
|
|
for unformatted files.
|
|
@item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for
|
|
unformatted files.
|
|
@end itemize
|
|
|
|
Using the option could look like this:
|
|
@smallexample
|
|
open(file='big.dat',form='unformatted',access='sequential', &
|
|
convert='big_endian')
|
|
@end smallexample
|
|
|
|
The value of the conversion can be queried by using
|
|
@code{INQUIRE(CONVERT=ch)}. The values returned are
|
|
@code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}.
|
|
|
|
@code{CONVERT} works between big- and little-endian for
|
|
@code{INTEGER} values of all supported kinds and for @code{REAL}
|
|
on IEEE systems of kinds 4 and 8. Conversion between different
|
|
``extended double'' types on different architectures such as
|
|
m68k and x86_64, which GNU Fortran
|
|
supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will
|
|
probably not work.
|
|
|
|
@emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
|
|
environment variable will override the CONVERT specifier in the
|
|
open statement}. This is to give control over data formats to
|
|
users who do not have the source code of their program available.
|
|
|
|
Using anything but the native representation for unformatted data
|
|
carries a significant speed overhead. If speed in this area matters
|
|
to you, it is best if you use this only for data that needs to be
|
|
portable.
|
|
|
|
@node OpenMP
|
|
@subsection OpenMP
|
|
@cindex OpenMP
|
|
|
|
OpenMP (Open Multi-Processing) is an application programming
|
|
interface (API) that supports multi-platform shared memory
|
|
multiprocessing programming in C/C++ and Fortran on many
|
|
architectures, including Unix and Microsoft Windows platforms.
|
|
It consists of a set of compiler directives, library routines,
|
|
and environment variables that influence run-time behavior.
|
|
|
|
GNU Fortran strives to be compatible to the
|
|
@uref{http://openmp.org/wp/openmp-specifications/,
|
|
OpenMP Application Program Interface v4.5}.
|
|
|
|
To enable the processing of the OpenMP directive @code{!$omp} in
|
|
free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp}
|
|
directives in fixed form; the @code{!$} conditional compilation sentinels
|
|
in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels
|
|
in fixed form, @command{gfortran} needs to be invoked with the
|
|
@option{-fopenmp}. This also arranges for automatic linking of the
|
|
GNU Offloading and Multi Processing Runtime Library
|
|
@ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
|
|
Library}.
|
|
|
|
The OpenMP Fortran runtime library routines are provided both in a
|
|
form of a Fortran 90 module named @code{omp_lib} and in a form of
|
|
a Fortran @code{include} file named @file{omp_lib.h}.
|
|
|
|
An example of a parallelized loop taken from Appendix A.1 of
|
|
the OpenMP Application Program Interface v2.5:
|
|
@smallexample
|
|
SUBROUTINE A1(N, A, B)
|
|
INTEGER I, N
|
|
REAL B(N), A(N)
|
|
!$OMP PARALLEL DO !I is private by default
|
|
DO I=2,N
|
|
B(I) = (A(I) + A(I-1)) / 2.0
|
|
ENDDO
|
|
!$OMP END PARALLEL DO
|
|
END SUBROUTINE A1
|
|
@end smallexample
|
|
|
|
Please note:
|
|
@itemize
|
|
@item
|
|
@option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays
|
|
will be allocated on the stack. When porting existing code to OpenMP,
|
|
this may lead to surprising results, especially to segmentation faults
|
|
if the stacksize is limited.
|
|
|
|
@item
|
|
On glibc-based systems, OpenMP enabled applications cannot be statically
|
|
linked due to limitations of the underlying pthreads-implementation. It
|
|
might be possible to get a working solution if
|
|
@command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added
|
|
to the command line. However, this is not supported by @command{gcc} and
|
|
thus not recommended.
|
|
@end itemize
|
|
|
|
@node OpenACC
|
|
@subsection OpenACC
|
|
@cindex OpenACC
|
|
|
|
OpenACC is an application programming interface (API) that supports
|
|
offloading of code to accelerator devices. It consists of a set of
|
|
compiler directives, library routines, and environment variables that
|
|
influence run-time behavior.
|
|
|
|
GNU Fortran strives to be compatible to the
|
|
@uref{http://www.openacc.org/, OpenACC Application Programming
|
|
Interface v2.0}.
|
|
|
|
To enable the processing of the OpenACC directive @code{!$acc} in
|
|
free-form source code; the @code{c$acc}, @code{*$acc} and @code{!$acc}
|
|
directives in fixed form; the @code{!$} conditional compilation
|
|
sentinels in free form; and the @code{c$}, @code{*$} and @code{!$}
|
|
sentinels in fixed form, @command{gfortran} needs to be invoked with
|
|
the @option{-fopenacc}. This also arranges for automatic linking of
|
|
the GNU Offloading and Multi Processing Runtime Library
|
|
@ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
|
|
Library}.
|
|
|
|
The OpenACC Fortran runtime library routines are provided both in a
|
|
form of a Fortran 90 module named @code{openacc} and in a form of a
|
|
Fortran @code{include} file named @file{openacc_lib.h}.
|
|
|
|
Note that this is an experimental feature, incomplete, and subject to
|
|
change in future versions of GCC. See
|
|
@uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
|
|
|
|
@node Argument list functions
|
|
@subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC}
|
|
@cindex argument list functions
|
|
@cindex @code{%VAL}
|
|
@cindex @code{%REF}
|
|
@cindex @code{%LOC}
|
|
|
|
GNU Fortran supports argument list functions @code{%VAL}, @code{%REF}
|
|
and @code{%LOC} statements, for backward compatibility with g77.
|
|
It is recommended that these should be used only for code that is
|
|
accessing facilities outside of GNU Fortran, such as operating system
|
|
or windowing facilities. It is best to constrain such uses to isolated
|
|
portions of a program--portions that deal specifically and exclusively
|
|
with low-level, system-dependent facilities. Such portions might well
|
|
provide a portable interface for use by the program as a whole, but are
|
|
themselves not portable, and should be thoroughly tested each time they
|
|
are rebuilt using a new compiler or version of a compiler.
|
|
|
|
@code{%VAL} passes a scalar argument by value, @code{%REF} passes it by
|
|
reference and @code{%LOC} passes its memory location. Since gfortran
|
|
already passes scalar arguments by reference, @code{%REF} is in effect
|
|
a do-nothing. @code{%LOC} has the same effect as a Fortran pointer.
|
|
|
|
An example of passing an argument by value to a C subroutine foo.:
|
|
@smallexample
|
|
C
|
|
C prototype void foo_ (float x);
|
|
C
|
|
external foo
|
|
real*4 x
|
|
x = 3.14159
|
|
call foo (%VAL (x))
|
|
end
|
|
@end smallexample
|
|
|
|
For details refer to the g77 manual
|
|
@uref{https://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}.
|
|
|
|
Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the
|
|
GNU Fortran testsuite are worth a look.
|
|
|
|
@node Read/Write after EOF marker
|
|
@subsection Read/Write after EOF marker
|
|
@cindex @code{EOF}
|
|
@cindex @code{BACKSPACE}
|
|
@cindex @code{REWIND}
|
|
|
|
Some legacy codes rely on allowing @code{READ} or @code{WRITE} after the
|
|
EOF file marker in order to find the end of a file. GNU Fortran normally
|
|
rejects these codes with a run-time error message and suggests the user
|
|
consider @code{BACKSPACE} or @code{REWIND} to properly position
|
|
the file before the EOF marker. As an extension, the run-time error may
|
|
be disabled using -std=legacy.
|
|
|
|
|
|
@node STRUCTURE and RECORD
|
|
@subsection @code{STRUCTURE} and @code{RECORD}
|
|
@cindex @code{STRUCTURE}
|
|
@cindex @code{RECORD}
|
|
|
|
Record structures are a pre-Fortran-90 vendor extension to create
|
|
user-defined aggregate data types. Support for record structures in GNU
|
|
Fortran can be enabled with the @option{-fdec-structure} compile flag.
|
|
If you have a choice, you should instead use Fortran 90's ``derived types'',
|
|
which have a different syntax.
|
|
|
|
In many cases, record structures can easily be converted to derived types.
|
|
To convert, replace @code{STRUCTURE /}@var{structure-name}@code{/}
|
|
by @code{TYPE} @var{type-name}. Additionally, replace
|
|
@code{RECORD /}@var{structure-name}@code{/} by
|
|
@code{TYPE(}@var{type-name}@code{)}. Finally, in the component access,
|
|
replace the period (@code{.}) by the percent sign (@code{%}).
|
|
|
|
Here is an example of code using the non portable record structure syntax:
|
|
|
|
@example
|
|
! Declaring a structure named ``item'' and containing three fields:
|
|
! an integer ID, an description string and a floating-point price.
|
|
STRUCTURE /item/
|
|
INTEGER id
|
|
CHARACTER(LEN=200) description
|
|
REAL price
|
|
END STRUCTURE
|
|
|
|
! Define two variables, an single record of type ``item''
|
|
! named ``pear'', and an array of items named ``store_catalog''
|
|
RECORD /item/ pear, store_catalog(100)
|
|
|
|
! We can directly access the fields of both variables
|
|
pear.id = 92316
|
|
pear.description = "juicy D'Anjou pear"
|
|
pear.price = 0.15
|
|
store_catalog(7).id = 7831
|
|
store_catalog(7).description = "milk bottle"
|
|
store_catalog(7).price = 1.2
|
|
|
|
! We can also manipulate the whole structure
|
|
store_catalog(12) = pear
|
|
print *, store_catalog(12)
|
|
@end example
|
|
|
|
@noindent
|
|
This code can easily be rewritten in the Fortran 90 syntax as following:
|
|
|
|
@example
|
|
! ``STRUCTURE /name/ ... END STRUCTURE'' becomes
|
|
! ``TYPE name ... END TYPE''
|
|
TYPE item
|
|
INTEGER id
|
|
CHARACTER(LEN=200) description
|
|
REAL price
|
|
END TYPE
|
|
|
|
! ``RECORD /name/ variable'' becomes ``TYPE(name) variable''
|
|
TYPE(item) pear, store_catalog(100)
|
|
|
|
! Instead of using a dot (.) to access fields of a record, the
|
|
! standard syntax uses a percent sign (%)
|
|
pear%id = 92316
|
|
pear%description = "juicy D'Anjou pear"
|
|
pear%price = 0.15
|
|
store_catalog(7)%id = 7831
|
|
store_catalog(7)%description = "milk bottle"
|
|
store_catalog(7)%price = 1.2
|
|
|
|
! Assignments of a whole variable do not change
|
|
store_catalog(12) = pear
|
|
print *, store_catalog(12)
|
|
@end example
|
|
|
|
@noindent
|
|
GNU Fortran implements STRUCTURES like derived types with the following
|
|
rules and exceptions:
|
|
|
|
@itemize @bullet
|
|
@item Structures act like derived types with the @code{SEQUENCE} attribute.
|
|
Otherwise they may contain no specifiers.
|
|
|
|
@item Structures may share names with other symbols. For example, the following
|
|
is invalid for derived types, but valid for structures:
|
|
|
|
@smallexample
|
|
structure /header/
|
|
! ...
|
|
end structure
|
|
record /header/ header
|
|
@end smallexample
|
|
|
|
@item Structure types may be declared nested within another parent structure.
|
|
The syntax is:
|
|
@smallexample
|
|
structure /type-name/
|
|
...
|
|
structure [/<type-name>/] <field-list>
|
|
...
|
|
@end smallexample
|
|
|
|
The type name may be ommitted, in which case the structure type itself is
|
|
anonymous, and other structures of the same type cannot be instantiated. The
|
|
following shows some examples:
|
|
|
|
@example
|
|
structure /appointment/
|
|
! nested structure definition: app_time is an array of two 'time'
|
|
structure /time/ app_time (2)
|
|
integer(1) hour, minute
|
|
end structure
|
|
character(10) memo
|
|
end structure
|
|
|
|
! The 'time' structure is still usable
|
|
record /time/ now
|
|
now = time(5, 30)
|
|
|
|
...
|
|
|
|
structure /appointment/
|
|
! anonymous nested structure definition
|
|
structure start, end
|
|
integer(1) hour, minute
|
|
end structure
|
|
character(10) memo
|
|
end structure
|
|
@end example
|
|
|
|
@item Structures may contain @code{UNION} blocks. For more detail see the
|
|
section on @ref{UNION and MAP}.
|
|
|
|
@item Structures support old-style initialization of components, like
|
|
those described in @ref{Old-style variable initialization}. For array
|
|
initializers, an initializer may contain a repeat specification of the form
|
|
@code{<literal-integer> * <constant-initializer>}. The value of the integer
|
|
indicates the number of times to repeat the constant initializer when expanding
|
|
the initializer list.
|
|
@end itemize
|
|
|
|
@node UNION and MAP
|
|
@subsection @code{UNION} and @code{MAP}
|
|
@cindex @code{UNION}
|
|
@cindex @code{MAP}
|
|
|
|
Unions are an old vendor extension which were commonly used with the
|
|
non-standard @ref{STRUCTURE and RECORD} extensions. Use of @code{UNION} and
|
|
@code{MAP} is automatically enabled with @option{-fdec-structure}.
|
|
|
|
A @code{UNION} declaration occurs within a structure; within the definition of
|
|
each union is a number of @code{MAP} blocks. Each @code{MAP} shares storage
|
|
with its sibling maps (in the same union), and the size of the union is the
|
|
size of the largest map within it, just as with unions in C. The major
|
|
difference is that component references do not indicate which union or map the
|
|
component is in (the compiler gets to figure that out).
|
|
|
|
Here is a small example:
|
|
@smallexample
|
|
structure /myunion/
|
|
union
|
|
map
|
|
character(2) w0, w1, w2
|
|
end map
|
|
map
|
|
character(6) long
|
|
end map
|
|
end union
|
|
end structure
|
|
|
|
record /myunion/ rec
|
|
! After this assignment...
|
|
rec.long = 'hello!'
|
|
|
|
! The following is true:
|
|
! rec.w0 === 'he'
|
|
! rec.w1 === 'll'
|
|
! rec.w2 === 'o!'
|
|
@end smallexample
|
|
|
|
The two maps share memory, and the size of the union is ultimately six bytes:
|
|
|
|
@example
|
|
0 1 2 3 4 5 6 Byte offset
|
|
-------------------------------
|
|
| | | | | | |
|
|
-------------------------------
|
|
|
|
^ W0 ^ W1 ^ W2 ^
|
|
\-------/ \-------/ \-------/
|
|
|
|
^ LONG ^
|
|
\---------------------------/
|
|
@end example
|
|
|
|
Following is an example mirroring the layout of an Intel x86_64 register:
|
|
|
|
@example
|
|
structure /reg/
|
|
union ! U0 ! rax
|
|
map
|
|
character(16) rx
|
|
end map
|
|
map
|
|
character(8) rh ! rah
|
|
union ! U1
|
|
map
|
|
character(8) rl ! ral
|
|
end map
|
|
map
|
|
character(8) ex ! eax
|
|
end map
|
|
map
|
|
character(4) eh ! eah
|
|
union ! U2
|
|
map
|
|
character(4) el ! eal
|
|
end map
|
|
map
|
|
character(4) x ! ax
|
|
end map
|
|
map
|
|
character(2) h ! ah
|
|
character(2) l ! al
|
|
end map
|
|
end union
|
|
end map
|
|
end union
|
|
end map
|
|
end union
|
|
end structure
|
|
record /reg/ a
|
|
|
|
! After this assignment...
|
|
a.rx = 'AAAAAAAA.BBB.C.D'
|
|
|
|
! The following is true:
|
|
a.rx === 'AAAAAAAA.BBB.C.D'
|
|
a.rh === 'AAAAAAAA'
|
|
a.rl === '.BBB.C.D'
|
|
a.ex === '.BBB.C.D'
|
|
a.eh === '.BBB'
|
|
a.el === '.C.D'
|
|
a.x === '.C.D'
|
|
a.h === '.C'
|
|
a.l === '.D'
|
|
@end example
|
|
|
|
@node Type variants for integer intrinsics
|
|
@subsection Type variants for integer intrinsics
|
|
@cindex intrinsics, integer
|
|
|
|
Similar to the D/C prefixes to real functions to specify the input/output
|
|
types, GNU Fortran offers B/I/J/K prefixes to integer functions for
|
|
compatibility with DEC programs. The types implied by each are:
|
|
|
|
@example
|
|
@code{B} - @code{INTEGER(kind=1)}
|
|
@code{I} - @code{INTEGER(kind=2)}
|
|
@code{J} - @code{INTEGER(kind=4)}
|
|
@code{K} - @code{INTEGER(kind=8)}
|
|
@end example
|
|
|
|
GNU Fortran supports these with the flag @option{-fdec-intrinsic-ints}.
|
|
Intrinsics for which prefixed versions are available and in what form are noted
|
|
in @ref{Intrinsic Procedures}. The complete list of supported intrinsics is
|
|
here:
|
|
|
|
@multitable @columnfractions .2 .2 .2 .2 .2
|
|
|
|
@headitem Intrinsic @tab B @tab I @tab J @tab K
|
|
|
|
@item @code{@ref{ABS}}
|
|
@tab @code{BABS} @tab @code{IIABS} @tab @code{JIABS} @tab @code{KIABS}
|
|
@item @code{@ref{BTEST}}
|
|
@tab @code{BBTEST} @tab @code{BITEST} @tab @code{BJTEST} @tab @code{BKTEST}
|
|
@item @code{@ref{IAND}}
|
|
@tab @code{BIAND} @tab @code{IIAND} @tab @code{JIAND} @tab @code{KIAND}
|
|
@item @code{@ref{IBCLR}}
|
|
@tab @code{BBCLR} @tab @code{IIBCLR} @tab @code{JIBCLR} @tab @code{KIBCLR}
|
|
@item @code{@ref{IBITS}}
|
|
@tab @code{BBITS} @tab @code{IIBITS} @tab @code{JIBITS} @tab @code{KIBITS}
|
|
@item @code{@ref{IBSET}}
|
|
@tab @code{BBSET} @tab @code{IIBSET} @tab @code{JIBSET} @tab @code{KIBSET}
|
|
@item @code{@ref{IEOR}}
|
|
@tab @code{BIEOR} @tab @code{IIEOR} @tab @code{JIEOR} @tab @code{KIEOR}
|
|
@item @code{@ref{IOR}}
|
|
@tab @code{BIOR} @tab @code{IIOR} @tab @code{JIOR} @tab @code{KIOR}
|
|
@item @code{@ref{ISHFT}}
|
|
@tab @code{BSHFT} @tab @code{IISHFT} @tab @code{JISHFT} @tab @code{KISHFT}
|
|
@item @code{@ref{ISHFTC}}
|
|
@tab @code{BSHFTC} @tab @code{IISHFTC} @tab @code{JISHFTC} @tab @code{KISHFTC}
|
|
@item @code{@ref{MOD}}
|
|
@tab @code{BMOD} @tab @code{IMOD} @tab @code{JMOD} @tab @code{KMOD}
|
|
@item @code{@ref{NOT}}
|
|
@tab @code{BNOT} @tab @code{INOT} @tab @code{JNOT} @tab @code{KNOT}
|
|
@item @code{@ref{REAL}}
|
|
@tab @code{--} @tab @code{FLOATI} @tab @code{FLOATJ} @tab @code{FLOATK}
|
|
@end multitable
|
|
|
|
@node AUTOMATIC and STATIC attributes
|
|
@subsection @code{AUTOMATIC} and @code{STATIC} attributes
|
|
@cindex variable attributes
|
|
@cindex @code{AUTOMATIC}
|
|
@cindex @code{STATIC}
|
|
|
|
With @option{-fdec-static} GNU Fortran supports the DEC extended attributes
|
|
@code{STATIC} and @code{AUTOMATIC} to provide explicit specification of entity
|
|
storage. These follow the syntax of the Fortran standard @code{SAVE} attribute.
|
|
|
|
@code{STATIC} is exactly equivalent to @code{SAVE}, and specifies that
|
|
an entity should be allocated in static memory. As an example, @code{STATIC}
|
|
local variables will retain their values across multiple calls to a function.
|
|
|
|
Entities marked @code{AUTOMATIC} will be stack automatic whenever possible.
|
|
@code{AUTOMATIC} is the default for local variables smaller than
|
|
@option{-fmax-stack-var-size}, unless @option{-fno-automatic} is given. This
|
|
attribute overrides @option{-fno-automatic}, @option{-fmax-stack-var-size}, and
|
|
blanket @code{SAVE} statements.
|
|
|
|
|
|
Examples:
|
|
|
|
@example
|
|
subroutine f
|
|
integer, automatic :: i ! automatic variable
|
|
integer x, y ! static variables
|
|
save
|
|
...
|
|
endsubroutine
|
|
@end example
|
|
@example
|
|
subroutine f
|
|
integer a, b, c, x, y, z
|
|
static :: x
|
|
save y
|
|
automatic z, c
|
|
! a, b, c, and z are automatic
|
|
! x and y are static
|
|
endsubroutine
|
|
@end example
|
|
@example
|
|
! Compiled with -fno-automatic
|
|
subroutine f
|
|
integer a, b, c, d
|
|
automatic :: a
|
|
! a is automatic; b, c, and d are static
|
|
endsubroutine
|
|
@end example
|
|
|
|
@node Extended math intrinsics
|
|
@subsection Extended math intrinsics
|
|
@cindex intrinsics, math
|
|
@cindex intrinsics, trigonometric functions
|
|
|
|
GNU Fortran supports an extended list of mathematical intrinsics with the
|
|
compile flag @option{-fdec-math} for compatability with legacy code.
|
|
These intrinsics are described fully in @ref{Intrinsic Procedures} where it is
|
|
noted that they are extensions and should be avoided whenever possible.
|
|
|
|
Specifically, @option{-fdec-math} enables the @ref{COTAN} intrinsic, and
|
|
trigonometric intrinsics which accept or produce values in degrees instead of
|
|
radians. Here is a summary of the new intrinsics:
|
|
|
|
@multitable @columnfractions .5 .5
|
|
@headitem Radians @tab Degrees
|
|
@item @code{@ref{ACOS}} @tab @code{@ref{ACOSD}}*
|
|
@item @code{@ref{ASIN}} @tab @code{@ref{ASIND}}*
|
|
@item @code{@ref{ATAN}} @tab @code{@ref{ATAND}}*
|
|
@item @code{@ref{ATAN2}} @tab @code{@ref{ATAN2D}}*
|
|
@item @code{@ref{COS}} @tab @code{@ref{COSD}}*
|
|
@item @code{@ref{COTAN}}* @tab @code{@ref{COTAND}}*
|
|
@item @code{@ref{SIN}} @tab @code{@ref{SIND}}*
|
|
@item @code{@ref{TAN}} @tab @code{@ref{TAND}}*
|
|
@end multitable
|
|
|
|
* Enabled with @option{-fdec-math}.
|
|
|
|
For advanced users, it may be important to know the implementation of these
|
|
functions. They are simply wrappers around the standard radian functions, which
|
|
have more accurate builtin versions. These functions convert their arguments
|
|
(or results) to degrees (or radians) by taking the value modulus 360 (or 2*pi)
|
|
and then multiplying it by a constant radian-to-degree (or degree-to-radian)
|
|
factor, as appropriate. The factor is computed at compile-time as 180/pi (or
|
|
pi/180).
|
|
|
|
@node Form feed as whitespace
|
|
@subsection Form feed as whitespace
|
|
@cindex form feed whitespace
|
|
|
|
Historically, legacy compilers allowed insertion of form feed characters ('\f',
|
|
ASCII 0xC) at the beginning of lines for formatted output to line printers,
|
|
though the Fortran standard does not mention this. GNU Fortran supports the
|
|
interpretation of form feed characters in source as whitespace for
|
|
compatibility.
|
|
|
|
@node TYPE as an alias for PRINT
|
|
@subsection TYPE as an alias for PRINT
|
|
@cindex type alias print
|
|
For compatibility, GNU Fortran will interpret @code{TYPE} statements as
|
|
@code{PRINT} statements with the flag @option{-fdec}. With this flag asserted,
|
|
the following two examples are equivalent:
|
|
|
|
@smallexample
|
|
TYPE *, 'hello world'
|
|
@end smallexample
|
|
|
|
@smallexample
|
|
PRINT *, 'hello world'
|
|
@end smallexample
|
|
|
|
@node %LOC as an rvalue
|
|
@subsection %LOC as an rvalue
|
|
@cindex LOC
|
|
Normally @code{%LOC} is allowed only in parameter lists. However the intrinsic
|
|
function @code{LOC} does the same thing, and is usable as the right-hand-side of
|
|
assignments. For compatibility, GNU Fortran supports the use of @code{%LOC} as
|
|
an alias for the builtin @code{LOC} with @option{-std=legacy}. With this
|
|
feature enabled the following two examples are equivalent:
|
|
|
|
@smallexample
|
|
integer :: i, l
|
|
l = %loc(i)
|
|
call sub(l)
|
|
@end smallexample
|
|
|
|
@smallexample
|
|
integer :: i
|
|
call sub(%loc(i))
|
|
@end smallexample
|
|
|
|
@node .XOR. operator
|
|
@subsection .XOR. operator
|
|
@cindex operators, xor
|
|
|
|
GNU Fortran supports @code{.XOR.} as a logical operator with @code{-std=legacy}
|
|
for compatibility with legacy code. @code{.XOR.} is equivalent to
|
|
@code{.NEQV.}. That is, the output is true if and only if the inputs differ.
|
|
|
|
@node Bitwise logical operators
|
|
@subsection Bitwise logical operators
|
|
@cindex logical, bitwise
|
|
|
|
With @option{-fdec}, GNU Fortran relaxes the type constraints on
|
|
logical operators to allow integer operands, and performs the corresponding
|
|
bitwise operation instead. This flag is for compatibility only, and should be
|
|
avoided in new code. Consider:
|
|
|
|
@smallexample
|
|
INTEGER :: i, j
|
|
i = z'33'
|
|
j = z'cc'
|
|
print *, i .AND. j
|
|
@end smallexample
|
|
|
|
In this example, compiled with @option{-fdec}, GNU Fortran will
|
|
replace the @code{.AND.} operation with a call to the intrinsic
|
|
@code{@ref{IAND}} function, yielding the bitwise-and of @code{i} and @code{j}.
|
|
|
|
Note that this conversion will occur if at least one operand is of integral
|
|
type. As a result, a logical operand will be converted to an integer when the
|
|
other operand is an integer in a logical operation. In this case,
|
|
@code{.TRUE.} is converted to @code{1} and @code{.FALSE.} to @code{0}.
|
|
|
|
Here is the mapping of logical operator to bitwise intrinsic used with
|
|
@option{-fdec}:
|
|
|
|
@multitable @columnfractions .25 .25 .5
|
|
@headitem Operator @tab Intrinsic @tab Bitwise operation
|
|
@item @code{.NOT.} @tab @code{@ref{NOT}} @tab complement
|
|
@item @code{.AND.} @tab @code{@ref{IAND}} @tab intersection
|
|
@item @code{.OR.} @tab @code{@ref{IOR}} @tab union
|
|
@item @code{.NEQV.} @tab @code{@ref{IEOR}} @tab exclusive or
|
|
@item @code{.EQV.} @tab @code{@ref{NOT}(@ref{IEOR})} @tab complement of exclusive or
|
|
@end multitable
|
|
|
|
@node Extended I/O specifiers
|
|
@subsection Extended I/O specifiers
|
|
@cindex @code{CARRIAGECONTROL}
|
|
@cindex @code{READONLY}
|
|
@cindex @code{SHARE}
|
|
@cindex @code{SHARED}
|
|
@cindex @code{NOSHARED}
|
|
@cindex I/O specifiers
|
|
|
|
GNU Fortran supports the additional legacy I/O specifiers
|
|
@code{CARRIAGECONTROL}, @code{READONLY}, and @code{SHARE} with the
|
|
compile flag @option{-fdec}, for compatibility.
|
|
|
|
@table @code
|
|
@item CARRIAGECONTROL
|
|
The @code{CARRIAGECONTROL} specifier allows a user to control line
|
|
termination settings between output records for an I/O unit. The specifier has
|
|
no meaning for readonly files. When @code{CARRAIGECONTROL} is specified upon
|
|
opening a unit for formatted writing, the exact @code{CARRIAGECONTROL} setting
|
|
determines what characters to write between output records. The syntax is:
|
|
|
|
@smallexample
|
|
OPEN(..., CARRIAGECONTROL=cc)
|
|
@end smallexample
|
|
|
|
Where @emph{cc} is a character expression that evaluates to one of the
|
|
following values:
|
|
|
|
@multitable @columnfractions .2 .8
|
|
@item @code{'LIST'} @tab One line feed between records (default)
|
|
@item @code{'FORTRAN'} @tab Legacy interpretation of the first character (see below)
|
|
@item @code{'NONE'} @tab No separator between records
|
|
@end multitable
|
|
|
|
With @code{CARRIAGECONTROL='FORTRAN'}, when a record is written, the first
|
|
character of the input record is not written, and instead determines the output
|
|
record separator as follows:
|
|
|
|
@multitable @columnfractions .3 .3 .4
|
|
@headitem Leading character @tab Meaning @tab Output separating character(s)
|
|
@item @code{'+'} @tab Overprinting @tab Carriage return only
|
|
@item @code{'-'} @tab New line @tab Line feed and carriage return
|
|
@item @code{'0'} @tab Skip line @tab Two line feeds and carriage return
|
|
@item @code{'1'} @tab New page @tab Form feed and carriage return
|
|
@item @code{'$'} @tab Prompting @tab Line feed (no carriage return)
|
|
@item @code{CHAR(0)} @tab Overprinting (no advance) @tab None
|
|
@end multitable
|
|
|
|
@item READONLY
|
|
The @code{READONLY} specifier may be given upon opening a unit, and is
|
|
equivalent to specifying @code{ACTION='READ'}, except that the file may not be
|
|
deleted on close (i.e. @code{CLOSE} with @code{STATUS="DELETE"}). The syntax
|
|
is:
|
|
|
|
@smallexample
|
|
@code{OPEN(..., READONLY)}
|
|
@end smallexample
|
|
|
|
@item SHARE
|
|
The @code{SHARE} specifier allows system-level locking on a unit upon opening
|
|
it for controlled access from multiple processes/threads. The @code{SHARE}
|
|
specifier has several forms:
|
|
|
|
@smallexample
|
|
OPEN(..., SHARE=sh)
|
|
OPEN(..., SHARED)
|
|
OPEN(..., NOSHARED)
|
|
@end smallexample
|
|
|
|
Where @emph{sh} in the first form is a character expression that evaluates to
|
|
a value as seen in the table below. The latter two forms are aliases
|
|
for particular values of @emph{sh}:
|
|
|
|
@multitable @columnfractions .3 .3 .4
|
|
@headitem Explicit form @tab Short form @tab Meaning
|
|
@item @code{SHARE='DENYRW'} @tab @code{NOSHARED} @tab Exclusive (write) lock
|
|
@item @code{SHARE='DENYNONE'} @tab @code{SHARED} @tab Shared (read) lock
|
|
@end multitable
|
|
|
|
In general only one process may hold an exclusive (write) lock for a given file
|
|
at a time, whereas many processes may hold shared (read) locks for the same
|
|
file.
|
|
|
|
The behavior of locking may vary with your operating system. On POSIX systems,
|
|
locking is implemented with @code{fcntl}. Consult your corresponding operating
|
|
system's manual pages for further details. Locking via @code{SHARE=} is not
|
|
supported on other systems.
|
|
|
|
@end table
|
|
|
|
@node Legacy PARAMETER statements
|
|
@subsection Legacy PARAMETER statements
|
|
@cindex PARAMETER
|
|
|
|
For compatibility, GNU Fortran supports legacy PARAMETER statements without
|
|
parentheses with @option{-std=legacy}. A warning is emitted if used with
|
|
@option{-std=gnu}, and an error is acknowledged with a real Fortran standard
|
|
flag (@option{-std=f95}, etc...). These statements take the following form:
|
|
|
|
@smallexample
|
|
implicit real (E)
|
|
parameter e = 2.718282
|
|
real c
|
|
parameter c = 3.0e8
|
|
@end smallexample
|
|
|
|
@node Default exponents
|
|
@subsection Default exponents
|
|
@cindex exponent
|
|
|
|
For compatibility, GNU Fortran supports a default exponent of zero in real
|
|
constants with @option{-fdec}. For example, @code{9e} would be
|
|
interpreted as @code{9e0}, rather than an error.
|
|
|
|
|
|
@node Extensions not implemented in GNU Fortran
|
|
@section Extensions not implemented in GNU Fortran
|
|
@cindex extensions, not implemented
|
|
|
|
The long history of the Fortran language, its wide use and broad
|
|
userbase, the large number of different compiler vendors and the lack of
|
|
some features crucial to users in the first standards have lead to the
|
|
existence of a number of important extensions to the language. While
|
|
some of the most useful or popular extensions are supported by the GNU
|
|
Fortran compiler, not all existing extensions are supported. This section
|
|
aims at listing these extensions and offering advice on how best make
|
|
code that uses them running with the GNU Fortran compiler.
|
|
|
|
@c More can be found here:
|
|
@c -- https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html
|
|
@c -- the list of Fortran and libgfortran bugs closed as WONTFIX:
|
|
@c http://tinyurl.com/2u4h5y
|
|
|
|
@menu
|
|
* ENCODE and DECODE statements::
|
|
* Variable FORMAT expressions::
|
|
@c * Q edit descriptor::
|
|
@c * TYPE and ACCEPT I/O Statements::
|
|
@c * DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers::
|
|
@c * Omitted arguments in procedure call::
|
|
* Alternate complex function syntax::
|
|
* Volatile COMMON blocks::
|
|
* OPEN( ... NAME=)::
|
|
@end menu
|
|
|
|
@node ENCODE and DECODE statements
|
|
@subsection @code{ENCODE} and @code{DECODE} statements
|
|
@cindex @code{ENCODE}
|
|
@cindex @code{DECODE}
|
|
|
|
GNU Fortran does not support the @code{ENCODE} and @code{DECODE}
|
|
statements. These statements are best replaced by @code{READ} and
|
|
@code{WRITE} statements involving internal files (@code{CHARACTER}
|
|
variables and arrays), which have been part of the Fortran standard since
|
|
Fortran 77. For example, replace a code fragment like
|
|
|
|
@smallexample
|
|
INTEGER*1 LINE(80)
|
|
REAL A, B, C
|
|
c ... Code that sets LINE
|
|
DECODE (80, 9000, LINE) A, B, C
|
|
9000 FORMAT (1X, 3(F10.5))
|
|
@end smallexample
|
|
|
|
@noindent
|
|
with the following:
|
|
|
|
@smallexample
|
|
CHARACTER(LEN=80) LINE
|
|
REAL A, B, C
|
|
c ... Code that sets LINE
|
|
READ (UNIT=LINE, FMT=9000) A, B, C
|
|
9000 FORMAT (1X, 3(F10.5))
|
|
@end smallexample
|
|
|
|
Similarly, replace a code fragment like
|
|
|
|
@smallexample
|
|
INTEGER*1 LINE(80)
|
|
REAL A, B, C
|
|
c ... Code that sets A, B and C
|
|
ENCODE (80, 9000, LINE) A, B, C
|
|
9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
|
|
@end smallexample
|
|
|
|
@noindent
|
|
with the following:
|
|
|
|
@smallexample
|
|
CHARACTER(LEN=80) LINE
|
|
REAL A, B, C
|
|
c ... Code that sets A, B and C
|
|
WRITE (UNIT=LINE, FMT=9000) A, B, C
|
|
9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
|
|
@end smallexample
|
|
|
|
|
|
@node Variable FORMAT expressions
|
|
@subsection Variable @code{FORMAT} expressions
|
|
@cindex @code{FORMAT}
|
|
|
|
A variable @code{FORMAT} expression is format statement which includes
|
|
angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU
|
|
Fortran does not support this legacy extension. The effect of variable
|
|
format expressions can be reproduced by using the more powerful (and
|
|
standard) combination of internal output and string formats. For example,
|
|
replace a code fragment like this:
|
|
|
|
@smallexample
|
|
WRITE(6,20) INT1
|
|
20 FORMAT(I<N+1>)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
with the following:
|
|
|
|
@smallexample
|
|
c Variable declaration
|
|
CHARACTER(LEN=20) FMT
|
|
c
|
|
c Other code here...
|
|
c
|
|
WRITE(FMT,'("(I", I0, ")")') N+1
|
|
WRITE(6,FMT) INT1
|
|
@end smallexample
|
|
|
|
@noindent
|
|
or with:
|
|
|
|
@smallexample
|
|
c Variable declaration
|
|
CHARACTER(LEN=20) FMT
|
|
c
|
|
c Other code here...
|
|
c
|
|
WRITE(FMT,*) N+1
|
|
WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1
|
|
@end smallexample
|
|
|
|
|
|
@node Alternate complex function syntax
|
|
@subsection Alternate complex function syntax
|
|
@cindex Complex function
|
|
|
|
Some Fortran compilers, including @command{g77}, let the user declare
|
|
complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as
|
|
well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy
|
|
extensions. @command{gfortran} accepts the latter form, which is more
|
|
common, but not the former.
|
|
|
|
|
|
@node Volatile COMMON blocks
|
|
@subsection Volatile @code{COMMON} blocks
|
|
@cindex @code{VOLATILE}
|
|
@cindex @code{COMMON}
|
|
|
|
Some Fortran compilers, including @command{g77}, let the user declare
|
|
@code{COMMON} with the @code{VOLATILE} attribute. This is
|
|
invalid standard Fortran syntax and is not supported by
|
|
@command{gfortran}. Note that @command{gfortran} accepts
|
|
@code{VOLATILE} variables in @code{COMMON} blocks since revision 4.3.
|
|
|
|
|
|
@node OPEN( ... NAME=)
|
|
@subsection @code{OPEN( ... NAME=)}
|
|
@cindex @code{NAM}
|
|
|
|
Some Fortran compilers, including @command{g77}, let the user declare
|
|
@code{OPEN( ... NAME=)}. This is
|
|
invalid standard Fortran syntax and is not supported by
|
|
@command{gfortran}. @code{OPEN( ... NAME=)} should be replaced
|
|
with @code{OPEN( ... FILE=)}.
|
|
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c ---------------------------------------------------------------------
|
|
@c Mixed-Language Programming
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Mixed-Language Programming
|
|
@chapter Mixed-Language Programming
|
|
@cindex Interoperability
|
|
@cindex Mixed-language programming
|
|
|
|
@menu
|
|
* Interoperability with C::
|
|
* GNU Fortran Compiler Directives::
|
|
* Non-Fortran Main Program::
|
|
* Naming and argument-passing conventions::
|
|
@end menu
|
|
|
|
This chapter is about mixed-language interoperability, but also applies
|
|
if one links Fortran code compiled by different compilers. In most cases,
|
|
use of the C Binding features of the Fortran 2003 standard is sufficient,
|
|
and their use is highly recommended.
|
|
|
|
|
|
@node Interoperability with C
|
|
@section Interoperability with C
|
|
|
|
@menu
|
|
* Intrinsic Types::
|
|
* Derived Types and struct::
|
|
* Interoperable Global Variables::
|
|
* Interoperable Subroutines and Functions::
|
|
* Working with Pointers::
|
|
* Further Interoperability of Fortran with C::
|
|
@end menu
|
|
|
|
Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a
|
|
standardized way to generate procedure and derived-type
|
|
declarations and global variables which are interoperable with C
|
|
(ISO/IEC 9899:1999). The @code{bind(C)} attribute has been added
|
|
to inform the compiler that a symbol shall be interoperable with C;
|
|
also, some constraints are added. Note, however, that not
|
|
all C features have a Fortran equivalent or vice versa. For instance,
|
|
neither C's unsigned integers nor C's functions with variable number
|
|
of arguments have an equivalent in Fortran.
|
|
|
|
Note that array dimensions are reversely ordered in C and that arrays in
|
|
C always start with index 0 while in Fortran they start by default with
|
|
1. Thus, an array declaration @code{A(n,m)} in Fortran matches
|
|
@code{A[m][n]} in C and accessing the element @code{A(i,j)} matches
|
|
@code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]};
|
|
assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}).
|
|
|
|
@node Intrinsic Types
|
|
@subsection Intrinsic Types
|
|
|
|
In order to ensure that exactly the same variable type and kind is used
|
|
in C and Fortran, the named constants shall be used which are defined in the
|
|
@code{ISO_C_BINDING} intrinsic module. That module contains named constants
|
|
for kind parameters and character named constants for the escape sequences
|
|
in C. For a list of the constants, see @ref{ISO_C_BINDING}.
|
|
|
|
For logical types, please note that the Fortran standard only guarantees
|
|
interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
|
|
logicals and C99 defines that @code{true} has the value 1 and @code{false}
|
|
the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL}
|
|
(with any kind parameter) gives an undefined result. (Passing other integer
|
|
values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the
|
|
integer is explicitly or implicitly casted to @code{_Bool}.)
|
|
|
|
|
|
|
|
@node Derived Types and struct
|
|
@subsection Derived Types and struct
|
|
|
|
For compatibility of derived types with @code{struct}, one needs to use
|
|
the @code{BIND(C)} attribute in the type declaration. For instance, the
|
|
following type declaration
|
|
|
|
@smallexample
|
|
USE ISO_C_BINDING
|
|
TYPE, BIND(C) :: myType
|
|
INTEGER(C_INT) :: i1, i2
|
|
INTEGER(C_SIGNED_CHAR) :: i3
|
|
REAL(C_DOUBLE) :: d1
|
|
COMPLEX(C_FLOAT_COMPLEX) :: c1
|
|
CHARACTER(KIND=C_CHAR) :: str(5)
|
|
END TYPE
|
|
@end smallexample
|
|
|
|
matches the following @code{struct} declaration in C
|
|
|
|
@smallexample
|
|
struct @{
|
|
int i1, i2;
|
|
/* Note: "char" might be signed or unsigned. */
|
|
signed char i3;
|
|
double d1;
|
|
float _Complex c1;
|
|
char str[5];
|
|
@} myType;
|
|
@end smallexample
|
|
|
|
Derived types with the C binding attribute shall not have the @code{sequence}
|
|
attribute, type parameters, the @code{extends} attribute, nor type-bound
|
|
procedures. Every component must be of interoperable type and kind and may not
|
|
have the @code{pointer} or @code{allocatable} attribute. The names of the
|
|
components are irrelevant for interoperability.
|
|
|
|
As there exist no direct Fortran equivalents, neither unions nor structs
|
|
with bit field or variable-length array members are interoperable.
|
|
|
|
@node Interoperable Global Variables
|
|
@subsection Interoperable Global Variables
|
|
|
|
Variables can be made accessible from C using the C binding attribute,
|
|
optionally together with specifying a binding name. Those variables
|
|
have to be declared in the declaration part of a @code{MODULE},
|
|
be of interoperable type, and have neither the @code{pointer} nor
|
|
the @code{allocatable} attribute.
|
|
|
|
@smallexample
|
|
MODULE m
|
|
USE myType_module
|
|
USE ISO_C_BINDING
|
|
integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag
|
|
type(myType), bind(C) :: tp
|
|
END MODULE
|
|
@end smallexample
|
|
|
|
Here, @code{_MyProject_flags} is the case-sensitive name of the variable
|
|
as seen from C programs while @code{global_flag} is the case-insensitive
|
|
name as seen from Fortran. If no binding name is specified, as for
|
|
@var{tp}, the C binding name is the (lowercase) Fortran binding name.
|
|
If a binding name is specified, only a single variable may be after the
|
|
double colon. Note of warning: You cannot use a global variable to
|
|
access @var{errno} of the C library as the C standard allows it to be
|
|
a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead.
|
|
|
|
@node Interoperable Subroutines and Functions
|
|
@subsection Interoperable Subroutines and Functions
|
|
|
|
Subroutines and functions have to have the @code{BIND(C)} attribute to
|
|
be compatible with C. The dummy argument declaration is relatively
|
|
straightforward. However, one needs to be careful because C uses
|
|
call-by-value by default while Fortran behaves usually similar to
|
|
call-by-reference. Furthermore, strings and pointers are handled
|
|
differently. Note that in Fortran 2003 and 2008 only explicit size
|
|
and assumed-size arrays are supported but not assumed-shape or
|
|
deferred-shape (i.e. allocatable or pointer) arrays. However, those
|
|
are allowed since the Technical Specification 29113, see
|
|
@ref{Further Interoperability of Fortran with C}
|
|
|
|
To pass a variable by value, use the @code{VALUE} attribute.
|
|
Thus, the following C prototype
|
|
|
|
@smallexample
|
|
@code{int func(int i, int *j)}
|
|
@end smallexample
|
|
|
|
matches the Fortran declaration
|
|
|
|
@smallexample
|
|
integer(c_int) function func(i,j)
|
|
use iso_c_binding, only: c_int
|
|
integer(c_int), VALUE :: i
|
|
integer(c_int) :: j
|
|
@end smallexample
|
|
|
|
Note that pointer arguments also frequently need the @code{VALUE} attribute,
|
|
see @ref{Working with Pointers}.
|
|
|
|
Strings are handled quite differently in C and Fortran. In C a string
|
|
is a @code{NUL}-terminated array of characters while in Fortran each string
|
|
has a length associated with it and is thus not terminated (by e.g.
|
|
@code{NUL}). For example, if one wants to use the following C function,
|
|
|
|
@smallexample
|
|
#include <stdio.h>
|
|
void print_C(char *string) /* equivalent: char string[] */
|
|
@{
|
|
printf("%s\n", string);
|
|
@}
|
|
@end smallexample
|
|
|
|
to print ``Hello World'' from Fortran, one can call it using
|
|
|
|
@smallexample
|
|
use iso_c_binding, only: C_CHAR, C_NULL_CHAR
|
|
interface
|
|
subroutine print_c(string) bind(C, name="print_C")
|
|
use iso_c_binding, only: c_char
|
|
character(kind=c_char) :: string(*)
|
|
end subroutine print_c
|
|
end interface
|
|
call print_c(C_CHAR_"Hello World"//C_NULL_CHAR)
|
|
@end smallexample
|
|
|
|
As the example shows, one needs to ensure that the
|
|
string is @code{NUL} terminated. Additionally, the dummy argument
|
|
@var{string} of @code{print_C} is a length-one assumed-size
|
|
array; using @code{character(len=*)} is not allowed. The example
|
|
above uses @code{c_char_"Hello World"} to ensure the string
|
|
literal has the right type; typically the default character
|
|
kind and @code{c_char} are the same and thus @code{"Hello World"}
|
|
is equivalent. However, the standard does not guarantee this.
|
|
|
|
The use of strings is now further illustrated using the C library
|
|
function @code{strncpy}, whose prototype is
|
|
|
|
@smallexample
|
|
char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
|
|
@end smallexample
|
|
|
|
The function @code{strncpy} copies at most @var{n} characters from
|
|
string @var{s2} to @var{s1} and returns @var{s1}. In the following
|
|
example, we ignore the return value:
|
|
|
|
@smallexample
|
|
use iso_c_binding
|
|
implicit none
|
|
character(len=30) :: str,str2
|
|
interface
|
|
! Ignore the return value of strncpy -> subroutine
|
|
! "restrict" is always assumed if we do not pass a pointer
|
|
subroutine strncpy(dest, src, n) bind(C)
|
|
import
|
|
character(kind=c_char), intent(out) :: dest(*)
|
|
character(kind=c_char), intent(in) :: src(*)
|
|
integer(c_size_t), value, intent(in) :: n
|
|
end subroutine strncpy
|
|
end interface
|
|
str = repeat('X',30) ! Initialize whole string with 'X'
|
|
call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, &
|
|
len(c_char_"Hello World",kind=c_size_t))
|
|
print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX"
|
|
end
|
|
@end smallexample
|
|
|
|
The intrinsic procedures are described in @ref{Intrinsic Procedures}.
|
|
|
|
@node Working with Pointers
|
|
@subsection Working with Pointers
|
|
|
|
C pointers are represented in Fortran via the special opaque derived type
|
|
@code{type(c_ptr)} (with private components). Thus one needs to
|
|
use intrinsic conversion procedures to convert from or to C pointers.
|
|
|
|
For some applications, using an assumed type (@code{TYPE(*)}) can be an
|
|
alternative to a C pointer; see
|
|
@ref{Further Interoperability of Fortran with C}.
|
|
|
|
For example,
|
|
|
|
@smallexample
|
|
use iso_c_binding
|
|
type(c_ptr) :: cptr1, cptr2
|
|
integer, target :: array(7), scalar
|
|
integer, pointer :: pa(:), ps
|
|
cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the
|
|
! array is contiguous if required by the C
|
|
! procedure
|
|
cptr2 = c_loc(scalar)
|
|
call c_f_pointer(cptr2, ps)
|
|
call c_f_pointer(cptr2, pa, shape=[7])
|
|
@end smallexample
|
|
|
|
When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument
|
|
has to be passed.
|
|
|
|
If a pointer is a dummy-argument of an interoperable procedure, it usually
|
|
has to be declared using the @code{VALUE} attribute. @code{void*}
|
|
matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone
|
|
matches @code{void**}.
|
|
|
|
Procedure pointers are handled analogously to pointers; the C type is
|
|
@code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are
|
|
@code{C_F_PROCPOINTER} and @code{C_FUNLOC}.
|
|
|
|
Let us consider two examples of actually passing a procedure pointer from
|
|
C to Fortran and vice versa. Note that these examples are also very
|
|
similar to passing ordinary pointers between both languages. First,
|
|
consider this code in C:
|
|
|
|
@smallexample
|
|
/* Procedure implemented in Fortran. */
|
|
void get_values (void (*)(double));
|
|
|
|
/* Call-back routine we want called from Fortran. */
|
|
void
|
|
print_it (double x)
|
|
@{
|
|
printf ("Number is %f.\n", x);
|
|
@}
|
|
|
|
/* Call Fortran routine and pass call-back to it. */
|
|
void
|
|
foobar ()
|
|
@{
|
|
get_values (&print_it);
|
|
@}
|
|
@end smallexample
|
|
|
|
A matching implementation for @code{get_values} in Fortran, that correctly
|
|
receives the procedure pointer from C and is able to call it, is given
|
|
in the following @code{MODULE}:
|
|
|
|
@smallexample
|
|
MODULE m
|
|
IMPLICIT NONE
|
|
|
|
! Define interface of call-back routine.
|
|
ABSTRACT INTERFACE
|
|
SUBROUTINE callback (x)
|
|
USE, INTRINSIC :: ISO_C_BINDING
|
|
REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x
|
|
END SUBROUTINE callback
|
|
END INTERFACE
|
|
|
|
CONTAINS
|
|
|
|
! Define C-bound procedure.
|
|
SUBROUTINE get_values (cproc) BIND(C)
|
|
USE, INTRINSIC :: ISO_C_BINDING
|
|
TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc
|
|
|
|
PROCEDURE(callback), POINTER :: proc
|
|
|
|
! Convert C to Fortran procedure pointer.
|
|
CALL C_F_PROCPOINTER (cproc, proc)
|
|
|
|
! Call it.
|
|
CALL proc (1.0_C_DOUBLE)
|
|
CALL proc (-42.0_C_DOUBLE)
|
|
CALL proc (18.12_C_DOUBLE)
|
|
END SUBROUTINE get_values
|
|
|
|
END MODULE m
|
|
@end smallexample
|
|
|
|
Next, we want to call a C routine that expects a procedure pointer argument
|
|
and pass it a Fortran procedure (which clearly must be interoperable!).
|
|
Again, the C function may be:
|
|
|
|
@smallexample
|
|
int
|
|
call_it (int (*func)(int), int arg)
|
|
@{
|
|
return func (arg);
|
|
@}
|
|
@end smallexample
|
|
|
|
It can be used as in the following Fortran code:
|
|
|
|
@smallexample
|
|
MODULE m
|
|
USE, INTRINSIC :: ISO_C_BINDING
|
|
IMPLICIT NONE
|
|
|
|
! Define interface of C function.
|
|
INTERFACE
|
|
INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C)
|
|
USE, INTRINSIC :: ISO_C_BINDING
|
|
TYPE(C_FUNPTR), INTENT(IN), VALUE :: func
|
|
INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
|
|
END FUNCTION call_it
|
|
END INTERFACE
|
|
|
|
CONTAINS
|
|
|
|
! Define procedure passed to C function.
|
|
! It must be interoperable!
|
|
INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C)
|
|
INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
|
|
double_it = arg + arg
|
|
END FUNCTION double_it
|
|
|
|
! Call C function.
|
|
SUBROUTINE foobar ()
|
|
TYPE(C_FUNPTR) :: cproc
|
|
INTEGER(KIND=C_INT) :: i
|
|
|
|
! Get C procedure pointer.
|
|
cproc = C_FUNLOC (double_it)
|
|
|
|
! Use it.
|
|
DO i = 1_C_INT, 10_C_INT
|
|
PRINT *, call_it (cproc, i)
|
|
END DO
|
|
END SUBROUTINE foobar
|
|
|
|
END MODULE m
|
|
@end smallexample
|
|
|
|
@node Further Interoperability of Fortran with C
|
|
@subsection Further Interoperability of Fortran with C
|
|
|
|
The Technical Specification ISO/IEC TS 29113:2012 on further
|
|
interoperability of Fortran with C extends the interoperability support
|
|
of Fortran 2003 and Fortran 2008. Besides removing some restrictions
|
|
and constraints, it adds assumed-type (@code{TYPE(*)}) and assumed-rank
|
|
(@code{dimension}) variables and allows for interoperability of
|
|
assumed-shape, assumed-rank and deferred-shape arrays, including
|
|
allocatables and pointers.
|
|
|
|
Note: Currently, GNU Fortran does not support the array descriptor
|
|
(dope vector) as specified in the Technical Specification, but uses
|
|
an array descriptor with different fields. The Chasm Language
|
|
Interoperability Tools, @url{http://chasm-interop.sourceforge.net/},
|
|
provide an interface to GNU Fortran's array descriptor.
|
|
|
|
The Technical Specification adds the following new features, which
|
|
are supported by GNU Fortran:
|
|
|
|
@itemize @bullet
|
|
|
|
@item The @code{ASYNCHRONOUS} attribute has been clarified and
|
|
extended to allow its use with asynchronous communication in
|
|
user-provided libraries such as in implementations of the
|
|
Message Passing Interface specification.
|
|
|
|
@item Many constraints have been relaxed, in particular for
|
|
the @code{C_LOC} and @code{C_F_POINTER} intrinsics.
|
|
|
|
@item The @code{OPTIONAL} attribute is now allowed for dummy
|
|
arguments; an absent argument matches a @code{NULL} pointer.
|
|
|
|
@item Assumed types (@code{TYPE(*)}) have been added, which may
|
|
only be used for dummy arguments. They are unlimited polymorphic
|
|
but contrary to @code{CLASS(*)} they do not contain any type
|
|
information, similar to C's @code{void *} pointers. Expressions
|
|
of any type and kind can be passed; thus, it can be used as
|
|
replacement for @code{TYPE(C_PTR)}, avoiding the use of
|
|
@code{C_LOC} in the caller.
|
|
|
|
Note, however, that @code{TYPE(*)} only accepts scalar arguments,
|
|
unless the @code{DIMENSION} is explicitly specified. As
|
|
@code{DIMENSION(*)} only supports array (including array elements) but
|
|
no scalars, it is not a full replacement for @code{C_LOC}. On the
|
|
other hand, assumed-type assumed-rank dummy arguments
|
|
(@code{TYPE(*), DIMENSION(..)}) allow for both scalars and arrays, but
|
|
require special code on the callee side to handle the array descriptor.
|
|
|
|
@item Assumed-rank arrays (@code{DIMENSION(..)}) as dummy argument
|
|
allow that scalars and arrays of any rank can be passed as actual
|
|
argument. As the Technical Specification does not provide for direct
|
|
means to operate with them, they have to be used either from the C side
|
|
or be converted using @code{C_LOC} and @code{C_F_POINTER} to scalars
|
|
or arrays of a specific rank. The rank can be determined using the
|
|
@code{RANK} intrinisic.
|
|
@end itemize
|
|
|
|
|
|
Currently unimplemented:
|
|
|
|
@itemize @bullet
|
|
|
|
@item GNU Fortran always uses an array descriptor, which does not
|
|
match the one of the Technical Specification. The
|
|
@code{ISO_Fortran_binding.h} header file and the C functions it
|
|
specifies are not available.
|
|
|
|
@item Using assumed-shape, assumed-rank and deferred-shape arrays in
|
|
@code{BIND(C)} procedures is not fully supported. In particular,
|
|
C interoperable strings of other length than one are not supported
|
|
as this requires the new array descriptor.
|
|
@end itemize
|
|
|
|
|
|
@node GNU Fortran Compiler Directives
|
|
@section GNU Fortran Compiler Directives
|
|
|
|
The Fortran standard describes how a conforming program shall
|
|
behave; however, the exact implementation is not standardized. In order
|
|
to allow the user to choose specific implementation details, compiler
|
|
directives can be used to set attributes of variables and procedures
|
|
which are not part of the standard. Whether a given attribute is
|
|
supported and its exact effects depend on both the operating system and
|
|
on the processor; see
|
|
@ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)}
|
|
for details.
|
|
|
|
For procedures and procedure pointers, the following attributes can
|
|
be used to change the calling convention:
|
|
|
|
@itemize
|
|
@item @code{CDECL} -- standard C calling convention
|
|
@item @code{STDCALL} -- convention where the called procedure pops the stack
|
|
@item @code{FASTCALL} -- part of the arguments are passed via registers
|
|
instead using the stack
|
|
@end itemize
|
|
|
|
Besides changing the calling convention, the attributes also influence
|
|
the decoration of the symbol name, e.g., by a leading underscore or by
|
|
a trailing at-sign followed by the number of bytes on the stack. When
|
|
assigning a procedure to a procedure pointer, both should use the same
|
|
calling convention.
|
|
|
|
On some systems, procedures and global variables (module variables and
|
|
@code{COMMON} blocks) need special handling to be accessible when they
|
|
are in a shared library. The following attributes are available:
|
|
|
|
@itemize
|
|
@item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL
|
|
@item @code{DLLIMPORT} -- reference the function or variable using a
|
|
global pointer
|
|
@end itemize
|
|
|
|
For dummy arguments, the @code{NO_ARG_CHECK} attribute can be used; in
|
|
other compilers, it is also known as @code{IGNORE_TKR}. For dummy arguments
|
|
with this attribute actual arguments of any type and kind (similar to
|
|
@code{TYPE(*)}), scalars and arrays of any rank (no equivalent
|
|
in Fortran standard) are accepted. As with @code{TYPE(*)}, the argument
|
|
is unlimited polymorphic and no type information is available.
|
|
Additionally, the argument may only be passed to dummy arguments
|
|
with the @code{NO_ARG_CHECK} attribute and as argument to the
|
|
@code{PRESENT} intrinsic function and to @code{C_LOC} of the
|
|
@code{ISO_C_BINDING} module.
|
|
|
|
Variables with @code{NO_ARG_CHECK} attribute shall be of assumed-type
|
|
(@code{TYPE(*)}; recommended) or of type @code{INTEGER}, @code{LOGICAL},
|
|
@code{REAL} or @code{COMPLEX}. They shall not have the @code{ALLOCATE},
|
|
@code{CODIMENSION}, @code{INTENT(OUT)}, @code{POINTER} or @code{VALUE}
|
|
attribute; furthermore, they shall be either scalar or of assumed-size
|
|
(@code{dimension(*)}). As @code{TYPE(*)}, the @code{NO_ARG_CHECK} attribute
|
|
requires an explicit interface.
|
|
|
|
@itemize
|
|
@item @code{NO_ARG_CHECK} -- disable the type, kind and rank checking
|
|
@end itemize
|
|
|
|
|
|
The attributes are specified using the syntax
|
|
|
|
@code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list}
|
|
|
|
where in free-form source code only whitespace is allowed before @code{!GCC$}
|
|
and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall
|
|
start in the first column.
|
|
|
|
For procedures, the compiler directives shall be placed into the body
|
|
of the procedure; for variables and procedure pointers, they shall be in
|
|
the same declaration part as the variable or procedure pointer.
|
|
|
|
|
|
|
|
@node Non-Fortran Main Program
|
|
@section Non-Fortran Main Program
|
|
|
|
@menu
|
|
* _gfortran_set_args:: Save command-line arguments
|
|
* _gfortran_set_options:: Set library option flags
|
|
* _gfortran_set_convert:: Set endian conversion
|
|
* _gfortran_set_record_marker:: Set length of record markers
|
|
* _gfortran_set_fpe:: Set when a Floating Point Exception should be raised
|
|
* _gfortran_set_max_subrecord_length:: Set subrecord length
|
|
@end menu
|
|
|
|
Even if you are doing mixed-language programming, it is very
|
|
likely that you do not need to know or use the information in this
|
|
section. Since it is about the internal structure of GNU Fortran,
|
|
it may also change in GCC minor releases.
|
|
|
|
When you compile a @code{PROGRAM} with GNU Fortran, a function
|
|
with the name @code{main} (in the symbol table of the object file)
|
|
is generated, which initializes the libgfortran library and then
|
|
calls the actual program which uses the name @code{MAIN__}, for
|
|
historic reasons. If you link GNU Fortran compiled procedures
|
|
to, e.g., a C or C++ program or to a Fortran program compiled by
|
|
a different compiler, the libgfortran library is not initialized
|
|
and thus a few intrinsic procedures do not work properly, e.g.
|
|
those for obtaining the command-line arguments.
|
|
|
|
Therefore, if your @code{PROGRAM} is not compiled with
|
|
GNU Fortran and the GNU Fortran compiled procedures require
|
|
intrinsics relying on the library initialization, you need to
|
|
initialize the library yourself. Using the default options,
|
|
gfortran calls @code{_gfortran_set_args} and
|
|
@code{_gfortran_set_options}. The initialization of the former
|
|
is needed if the called procedures access the command line
|
|
(and for backtracing); the latter sets some flags based on the
|
|
standard chosen or to enable backtracing. In typical programs,
|
|
it is not necessary to call any initialization function.
|
|
|
|
If your @code{PROGRAM} is compiled with GNU Fortran, you shall
|
|
not call any of the following functions. The libgfortran
|
|
initialization functions are shown in C syntax but using C
|
|
bindings they are also accessible from Fortran.
|
|
|
|
|
|
@node _gfortran_set_args
|
|
@subsection @code{_gfortran_set_args} --- Save command-line arguments
|
|
@fnindex _gfortran_set_args
|
|
@cindex libgfortran initialization, set_args
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
@code{_gfortran_set_args} saves the command-line arguments; this
|
|
initialization is required if any of the command-line intrinsics
|
|
is called. Additionally, it shall be called if backtracing is
|
|
enabled (see @code{_gfortran_set_options}).
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_set_args (int argc, char *argv[])}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{argc} @tab number of command line argument strings
|
|
@item @var{argv} @tab the command-line argument strings; argv[0]
|
|
is the pathname of the executable itself.
|
|
@end multitable
|
|
|
|
@item @emph{Example}:
|
|
@smallexample
|
|
int main (int argc, char *argv[])
|
|
@{
|
|
/* Initialize libgfortran. */
|
|
_gfortran_set_args (argc, argv);
|
|
return 0;
|
|
@}
|
|
@end smallexample
|
|
@end table
|
|
|
|
|
|
@node _gfortran_set_options
|
|
@subsection @code{_gfortran_set_options} --- Set library option flags
|
|
@fnindex _gfortran_set_options
|
|
@cindex libgfortran initialization, set_options
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
@code{_gfortran_set_options} sets several flags related to the Fortran
|
|
standard to be used, whether backtracing should be enabled
|
|
and whether range checks should be performed. The syntax allows for
|
|
upward compatibility since the number of passed flags is specified; for
|
|
non-passed flags, the default value is used. See also
|
|
@pxref{Code Gen Options}. Please note that not all flags are actually
|
|
used.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_set_options (int num, int options[])}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{num} @tab number of options passed
|
|
@item @var{argv} @tab The list of flag values
|
|
@end multitable
|
|
|
|
@item @emph{option flag list}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{option}[0] @tab Allowed standard; can give run-time errors
|
|
if e.g. an input-output edit descriptor is invalid in a given standard.
|
|
Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1),
|
|
@code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4), @code{GFC_STD_F95}
|
|
(8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU} (32),
|
|
@code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128),
|
|
@code{GFC_STD_F2008_OBS} (256) and GFC_STD_F2008_TS (512). Default:
|
|
@code{GFC_STD_F95_OBS | GFC_STD_F95_DEL | GFC_STD_F95 | GFC_STD_F2003
|
|
| GFC_STD_F2008 | GFC_STD_F2008_TS | GFC_STD_F2008_OBS | GFC_STD_F77
|
|
| GFC_STD_GNU | GFC_STD_LEGACY}.
|
|
@item @var{option}[1] @tab Standard-warning flag; prints a warning to
|
|
standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}.
|
|
@item @var{option}[2] @tab If non zero, enable pedantic checking.
|
|
Default: off.
|
|
@item @var{option}[3] @tab Unused.
|
|
@item @var{option}[4] @tab If non zero, enable backtracing on run-time
|
|
errors. Default: off. (Default in the compiler: on.)
|
|
Note: Installs a signal handler and requires command-line
|
|
initialization using @code{_gfortran_set_args}.
|
|
@item @var{option}[5] @tab If non zero, supports signed zeros.
|
|
Default: enabled.
|
|
@item @var{option}[6] @tab Enables run-time checking. Possible values
|
|
are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2),
|
|
GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (16), GFC_RTCHECK_POINTER (32).
|
|
Default: disabled.
|
|
@item @var{option}[7] @tab Unused.
|
|
@item @var{option}[8] @tab Show a warning when invoking @code{STOP} and
|
|
@code{ERROR STOP} if a floating-point exception occurred. Possible values
|
|
are (bitwise or-ed) @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
|
|
@code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
|
|
@code{GFC_FPE_UNDERFLOW} (16), @code{GFC_FPE_INEXACT} (32). Default: None (0).
|
|
(Default in the compiler: @code{GFC_FPE_INVALID | GFC_FPE_DENORMAL |
|
|
GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW}.)
|
|
@end multitable
|
|
|
|
@item @emph{Example}:
|
|
@smallexample
|
|
/* Use gfortran 4.9 default options. */
|
|
static int options[] = @{68, 511, 0, 0, 1, 1, 0, 0, 31@};
|
|
_gfortran_set_options (9, &options);
|
|
@end smallexample
|
|
@end table
|
|
|
|
|
|
@node _gfortran_set_convert
|
|
@subsection @code{_gfortran_set_convert} --- Set endian conversion
|
|
@fnindex _gfortran_set_convert
|
|
@cindex libgfortran initialization, set_convert
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
@code{_gfortran_set_convert} set the representation of data for
|
|
unformatted files.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_set_convert (int conv)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{conv} @tab Endian conversion, possible values:
|
|
GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1),
|
|
GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3).
|
|
@end multitable
|
|
|
|
@item @emph{Example}:
|
|
@smallexample
|
|
int main (int argc, char *argv[])
|
|
@{
|
|
/* Initialize libgfortran. */
|
|
_gfortran_set_args (argc, argv);
|
|
_gfortran_set_convert (1);
|
|
return 0;
|
|
@}
|
|
@end smallexample
|
|
@end table
|
|
|
|
|
|
@node _gfortran_set_record_marker
|
|
@subsection @code{_gfortran_set_record_marker} --- Set length of record markers
|
|
@fnindex _gfortran_set_record_marker
|
|
@cindex libgfortran initialization, set_record_marker
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
@code{_gfortran_set_record_marker} sets the length of record markers
|
|
for unformatted files.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_set_record_marker (int val)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{val} @tab Length of the record marker; valid values
|
|
are 4 and 8. Default is 4.
|
|
@end multitable
|
|
|
|
@item @emph{Example}:
|
|
@smallexample
|
|
int main (int argc, char *argv[])
|
|
@{
|
|
/* Initialize libgfortran. */
|
|
_gfortran_set_args (argc, argv);
|
|
_gfortran_set_record_marker (8);
|
|
return 0;
|
|
@}
|
|
@end smallexample
|
|
@end table
|
|
|
|
|
|
@node _gfortran_set_fpe
|
|
@subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps
|
|
@fnindex _gfortran_set_fpe
|
|
@cindex libgfortran initialization, set_fpe
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
@code{_gfortran_set_fpe} enables floating point exception traps for
|
|
the specified exceptions. On most systems, this will result in a
|
|
SIGFPE signal being sent and the program being aborted.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_set_fpe (int val)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{option}[0] @tab IEEE exceptions. Possible values are
|
|
(bitwise or-ed) zero (0, default) no trapping,
|
|
@code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
|
|
@code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
|
|
@code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32).
|
|
@end multitable
|
|
|
|
@item @emph{Example}:
|
|
@smallexample
|
|
int main (int argc, char *argv[])
|
|
@{
|
|
/* Initialize libgfortran. */
|
|
_gfortran_set_args (argc, argv);
|
|
/* FPE for invalid operations such as SQRT(-1.0). */
|
|
_gfortran_set_fpe (1);
|
|
return 0;
|
|
@}
|
|
@end smallexample
|
|
@end table
|
|
|
|
|
|
@node _gfortran_set_max_subrecord_length
|
|
@subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length
|
|
@fnindex _gfortran_set_max_subrecord_length
|
|
@cindex libgfortran initialization, set_max_subrecord_length
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
@code{_gfortran_set_max_subrecord_length} set the maximum length
|
|
for a subrecord. This option only makes sense for testing and
|
|
debugging of unformatted I/O.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_set_max_subrecord_length (int val)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{val} @tab the maximum length for a subrecord;
|
|
the maximum permitted value is 2147483639, which is also
|
|
the default.
|
|
@end multitable
|
|
|
|
@item @emph{Example}:
|
|
@smallexample
|
|
int main (int argc, char *argv[])
|
|
@{
|
|
/* Initialize libgfortran. */
|
|
_gfortran_set_args (argc, argv);
|
|
_gfortran_set_max_subrecord_length (8);
|
|
return 0;
|
|
@}
|
|
@end smallexample
|
|
@end table
|
|
|
|
|
|
@node Naming and argument-passing conventions
|
|
@section Naming and argument-passing conventions
|
|
|
|
This section gives an overview about the naming convention of procedures
|
|
and global variables and about the argument passing conventions used by
|
|
GNU Fortran. If a C binding has been specified, the naming convention
|
|
and some of the argument-passing conventions change. If possible,
|
|
mixed-language and mixed-compiler projects should use the better defined
|
|
C binding for interoperability. See @pxref{Interoperability with C}.
|
|
|
|
@menu
|
|
* Naming conventions::
|
|
* Argument passing conventions::
|
|
@end menu
|
|
|
|
|
|
@node Naming conventions
|
|
@subsection Naming conventions
|
|
|
|
According the Fortran standard, valid Fortran names consist of a letter
|
|
between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0},
|
|
@code{1} to @code{9} and underscores (@code{_}) with the restriction
|
|
that names may only start with a letter. As vendor extension, the
|
|
dollar sign (@code{$}) is additionally permitted with the option
|
|
@option{-fdollar-ok}, but not as first character and only if the
|
|
target system supports it.
|
|
|
|
By default, the procedure name is the lower-cased Fortran name with an
|
|
appended underscore (@code{_}); using @option{-fno-underscoring} no
|
|
underscore is appended while @code{-fsecond-underscore} appends two
|
|
underscores. Depending on the target system and the calling convention,
|
|
the procedure might be additionally dressed; for instance, on 32bit
|
|
Windows with @code{stdcall}, an at-sign @code{@@} followed by an integer
|
|
number is appended. For the changing the calling convention, see
|
|
@pxref{GNU Fortran Compiler Directives}.
|
|
|
|
For common blocks, the same convention is used, i.e. by default an
|
|
underscore is appended to the lower-cased Fortran name. Blank commons
|
|
have the name @code{__BLNK__}.
|
|
|
|
For procedures and variables declared in the specification space of a
|
|
module, the name is formed by @code{__}, followed by the lower-cased
|
|
module name, @code{_MOD_}, and the lower-cased Fortran name. Note that
|
|
no underscore is appended.
|
|
|
|
|
|
@node Argument passing conventions
|
|
@subsection Argument passing conventions
|
|
|
|
Subroutines do not return a value (matching C99's @code{void}) while
|
|
functions either return a value as specified in the platform ABI or
|
|
the result variable is passed as hidden argument to the function and
|
|
no result is returned. A hidden result variable is used when the
|
|
result variable is an array or of type @code{CHARACTER}.
|
|
|
|
Arguments are passed according to the platform ABI. In particular,
|
|
complex arguments might not be compatible to a struct with two real
|
|
components for the real and imaginary part. The argument passing
|
|
matches the one of C99's @code{_Complex}. Functions with scalar
|
|
complex result variables return their value and do not use a
|
|
by-reference argument. Note that with the @option{-ff2c} option,
|
|
the argument passing is modified and no longer completely matches
|
|
the platform ABI. Some other Fortran compilers use @code{f2c}
|
|
semantic by default; this might cause problems with
|
|
interoperablility.
|
|
|
|
GNU Fortran passes most arguments by reference, i.e. by passing a
|
|
pointer to the data. Note that the compiler might use a temporary
|
|
variable into which the actual argument has been copied, if required
|
|
semantically (copy-in/copy-out).
|
|
|
|
For arguments with @code{ALLOCATABLE} and @code{POINTER}
|
|
attribute (including procedure pointers), a pointer to the pointer
|
|
is passed such that the pointer address can be modified in the
|
|
procedure.
|
|
|
|
For dummy arguments with the @code{VALUE} attribute: Scalar arguments
|
|
of the type @code{INTEGER}, @code{LOGICAL}, @code{REAL} and
|
|
@code{COMPLEX} are passed by value according to the platform ABI.
|
|
(As vendor extension and not recommended, using @code{%VAL()} in the
|
|
call to a procedure has the same effect.) For @code{TYPE(C_PTR)} and
|
|
procedure pointers, the pointer itself is passed such that it can be
|
|
modified without affecting the caller.
|
|
@c FIXME: Document how VALUE is handled for CHARACTER, TYPE,
|
|
@c CLASS and arrays, i.e. whether the copy-in is done in the caller
|
|
@c or in the callee.
|
|
|
|
For Boolean (@code{LOGICAL}) arguments, please note that GCC expects
|
|
only the integer value 0 and 1. If a GNU Fortran @code{LOGICAL}
|
|
variable contains another integer value, the result is undefined.
|
|
As some other Fortran compilers use @math{-1} for @code{.TRUE.},
|
|
extra care has to be taken -- such as passing the value as
|
|
@code{INTEGER}. (The same value restriction also applies to other
|
|
front ends of GCC, e.g. to GCC's C99 compiler for @code{_Bool}
|
|
or GCC's Ada compiler for @code{Boolean}.)
|
|
|
|
For arguments of @code{CHARACTER} type, the character length is passed
|
|
as hidden argument. For deferred-length strings, the value is passed
|
|
by reference, otherwise by value. The character length has the type
|
|
@code{INTEGER(kind=4)}. Note with C binding, @code{CHARACTER(len=1)}
|
|
result variables are returned according to the platform ABI and no
|
|
hidden length argument is used for dummy arguments; with @code{VALUE},
|
|
those variables are passed by value.
|
|
|
|
For @code{OPTIONAL} dummy arguments, an absent argument is denoted
|
|
by a NULL pointer, except for scalar dummy arguments of type
|
|
@code{INTEGER}, @code{LOGICAL}, @code{REAL} and @code{COMPLEX}
|
|
which have the @code{VALUE} attribute. For those, a hidden Boolean
|
|
argument (@code{logical(kind=C_bool),value}) is used to indicate
|
|
whether the argument is present.
|
|
|
|
Arguments which are assumed-shape, assumed-rank or deferred-rank
|
|
arrays or, with @option{-fcoarray=lib}, allocatable scalar coarrays use
|
|
an array descriptor. All other arrays pass the address of the
|
|
first element of the array. With @option{-fcoarray=lib}, the token
|
|
and the offset belonging to nonallocatable coarrays dummy arguments
|
|
are passed as hidden argument along the character length hidden
|
|
arguments. The token is an oparque pointer identifying the coarray
|
|
and the offset is a passed-by-value integer of kind @code{C_PTRDIFF_T},
|
|
denoting the byte offset between the base address of the coarray and
|
|
the passed scalar or first element of the passed array.
|
|
|
|
The arguments are passed in the following order
|
|
@itemize @bullet
|
|
@item Result variable, when the function result is passed by reference
|
|
@item Character length of the function result, if it is a of type
|
|
@code{CHARACTER} and no C binding is used
|
|
@item The arguments in the order in which they appear in the Fortran
|
|
declaration
|
|
@item The the present status for optional arguments with value attribute,
|
|
which are internally passed by value
|
|
@item The character length and/or coarray token and offset for the first
|
|
argument which is a @code{CHARACTER} or a nonallocatable coarray dummy
|
|
argument, followed by the hidden arguments of the next dummy argument
|
|
of such a type
|
|
@end itemize
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Coarray Programming
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Coarray Programming
|
|
@chapter Coarray Programming
|
|
@cindex Coarrays
|
|
|
|
@menu
|
|
* Type and enum ABI Documentation::
|
|
* Function ABI Documentation::
|
|
@end menu
|
|
|
|
|
|
@node Type and enum ABI Documentation
|
|
@section Type and enum ABI Documentation
|
|
|
|
@menu
|
|
* caf_token_t::
|
|
* caf_register_t::
|
|
* caf_deregister_t::
|
|
* caf_reference_t::
|
|
@end menu
|
|
|
|
@node caf_token_t
|
|
@subsection @code{caf_token_t}
|
|
|
|
Typedef of type @code{void *} on the compiler side. Can be any data
|
|
type on the library side.
|
|
|
|
@node caf_register_t
|
|
@subsection @code{caf_register_t}
|
|
|
|
Indicates which kind of coarray variable should be registered.
|
|
|
|
@verbatim
|
|
typedef enum caf_register_t {
|
|
CAF_REGTYPE_COARRAY_STATIC,
|
|
CAF_REGTYPE_COARRAY_ALLOC,
|
|
CAF_REGTYPE_LOCK_STATIC,
|
|
CAF_REGTYPE_LOCK_ALLOC,
|
|
CAF_REGTYPE_CRITICAL,
|
|
CAF_REGTYPE_EVENT_STATIC,
|
|
CAF_REGTYPE_EVENT_ALLOC,
|
|
CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY,
|
|
CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY
|
|
}
|
|
caf_register_t;
|
|
@end verbatim
|
|
|
|
The values @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and
|
|
@code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} are for allocatable components
|
|
in derived type coarrays only. The first one sets up the token without
|
|
allocating memory for allocatable component. The latter one only allocates the
|
|
memory for an allocatable component in a derived type coarray. The token
|
|
needs to be setup previously by the REGISTER_ONLY. This allows to have
|
|
allocatable components un-allocated on some images. The status whether an
|
|
allocatable component is allocated on a remote image can be queried by
|
|
@code{_caf_is_present} which used internally by the @code{ALLOCATED}
|
|
intrinsic.
|
|
|
|
@node caf_deregister_t
|
|
@subsection @code{caf_deregister_t}
|
|
|
|
@verbatim
|
|
typedef enum caf_deregister_t {
|
|
CAF_DEREGTYPE_COARRAY_DEREGISTER,
|
|
CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY
|
|
}
|
|
caf_deregister_t;
|
|
@end verbatim
|
|
|
|
Allows to specifiy the type of deregistration of a coarray object. The
|
|
@code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} flag is only allowed for
|
|
allocatable components in derived type coarrays.
|
|
|
|
@node caf_reference_t
|
|
@subsection @code{caf_reference_t}
|
|
|
|
The structure used for implementing arbitrary reference chains.
|
|
A @code{CAF_REFERENCE_T} allows to specify a component reference or any kind
|
|
of array reference of any rank supported by gfortran. For array references all
|
|
kinds as known by the compiler/Fortran standard are supported indicated by
|
|
a @code{MODE}.
|
|
|
|
@verbatim
|
|
typedef enum caf_ref_type_t {
|
|
/* Reference a component of a derived type, either regular one or an
|
|
allocatable or pointer type. For regular ones idx in caf_reference_t is
|
|
set to -1. */
|
|
CAF_REF_COMPONENT,
|
|
/* Reference an allocatable array. */
|
|
CAF_REF_ARRAY,
|
|
/* Reference a non-allocatable/non-pointer array. I.e., the coarray object
|
|
has no array descriptor associated and the addressing is done
|
|
completely using the ref. */
|
|
CAF_REF_STATIC_ARRAY
|
|
} caf_ref_type_t;
|
|
@end verbatim
|
|
|
|
@verbatim
|
|
typedef enum caf_array_ref_t {
|
|
/* No array ref. This terminates the array ref. */
|
|
CAF_ARR_REF_NONE = 0,
|
|
/* Reference array elements given by a vector. Only for this mode
|
|
caf_reference_t.u.a.dim[i].v is valid. */
|
|
CAF_ARR_REF_VECTOR,
|
|
/* A full array ref (:). */
|
|
CAF_ARR_REF_FULL,
|
|
/* Reference a range on elements given by start, end and stride. */
|
|
CAF_ARR_REF_RANGE,
|
|
/* Only a single item is referenced given in the start member. */
|
|
CAF_ARR_REF_SINGLE,
|
|
/* An array ref of the kind (i:), where i is an arbitrary valid index in the
|
|
array. The index i is given in the start member. */
|
|
CAF_ARR_REF_OPEN_END,
|
|
/* An array ref of the kind (:i), where the lower bound of the array ref
|
|
is given by the remote side. The index i is given in the end member. */
|
|
CAF_ARR_REF_OPEN_START
|
|
} caf_array_ref_t;
|
|
@end verbatim
|
|
|
|
@verbatim
|
|
/* References to remote components of a derived type. */
|
|
typedef struct caf_reference_t {
|
|
/* A pointer to the next ref or NULL. */
|
|
struct caf_reference_t *next;
|
|
/* The type of the reference. */
|
|
/* caf_ref_type_t, replaced by int to allow specification in fortran FE. */
|
|
int type;
|
|
/* The size of an item referenced in bytes. I.e. in an array ref this is
|
|
the factor to advance the array pointer with to get to the next item.
|
|
For component refs this gives just the size of the element referenced. */
|
|
size_t item_size;
|
|
union {
|
|
struct {
|
|
/* The offset (in bytes) of the component in the derived type.
|
|
Unused for allocatable or pointer components. */
|
|
ptrdiff_t offset;
|
|
/* The offset (in bytes) to the caf_token associated with this
|
|
component. NULL, when not allocatable/pointer ref. */
|
|
ptrdiff_t caf_token_offset;
|
|
} c;
|
|
struct {
|
|
/* The mode of the array ref. See CAF_ARR_REF_*. */
|
|
/* caf_array_ref_t, replaced by unsigend char to allow specification in
|
|
fortran FE. */
|
|
unsigned char mode[GFC_MAX_DIMENSIONS];
|
|
/* The type of a static array. Unset for array's with descriptors. */
|
|
int static_array_type;
|
|
/* Subscript refs (s) or vector refs (v). */
|
|
union {
|
|
struct {
|
|
/* The start and end boundary of the ref and the stride. */
|
|
index_type start, end, stride;
|
|
} s;
|
|
struct {
|
|
/* nvec entries of kind giving the elements to reference. */
|
|
void *vector;
|
|
/* The number of entries in vector. */
|
|
size_t nvec;
|
|
/* The integer kind used for the elements in vector. */
|
|
int kind;
|
|
} v;
|
|
} dim[GFC_MAX_DIMENSIONS];
|
|
} a;
|
|
} u;
|
|
} caf_reference_t;
|
|
@end verbatim
|
|
|
|
The references make up a single linked list of reference operations. The
|
|
@code{NEXT} member links to the next reference or NULL to indicate the end of
|
|
the chain. Component and array refs can be arbitrarly mixed as long as they
|
|
comply to the Fortran standard.
|
|
|
|
@emph{NOTES}
|
|
The member @code{STATIC_ARRAY_TYPE} is used only when the @code{TYPE} is
|
|
@code{CAF_REF_STATIC_ARRAY}. The member gives the type of the data referenced.
|
|
Because no array descriptor is available for a descriptor-less array and
|
|
type conversion still needs to take place the type is transported here.
|
|
|
|
At the moment @code{CAF_ARR_REF_VECTOR} is not implemented in the front end for
|
|
descriptor-less arrays. The library caf_single has untested support for it.
|
|
|
|
|
|
@node Function ABI Documentation
|
|
@section Function ABI Documentation
|
|
|
|
@menu
|
|
* _gfortran_caf_init:: Initialiation function
|
|
* _gfortran_caf_finish:: Finalization function
|
|
* _gfortran_caf_this_image:: Querying the image number
|
|
* _gfortran_caf_num_images:: Querying the maximal number of images
|
|
* _gfortran_caf_register:: Registering coarrays
|
|
* _gfortran_caf_deregister:: Deregistering coarrays
|
|
* _gfortran_caf_is_present:: Query whether an allocatable component in a derived type coarray is allocated
|
|
* _gfortran_caf_send:: Sending data from a local image to a remote image
|
|
* _gfortran_caf_get:: Getting data from a remote image
|
|
* _gfortran_caf_sendget:: Sending data between remote images
|
|
* _gfortran_caf_send_by_ref:: Sending data from a local image to a remote image using enhanced references
|
|
* _gfortran_caf_get_by_ref:: Getting data from a remote image using enhanced references
|
|
* _gfortran_caf_sendget_by_ref:: Sending data between remote images using enhanced references
|
|
* _gfortran_caf_lock:: Locking a lock variable
|
|
* _gfortran_caf_unlock:: Unlocking a lock variable
|
|
* _gfortran_caf_event_post:: Post an event
|
|
* _gfortran_caf_event_wait:: Wait that an event occurred
|
|
* _gfortran_caf_event_query:: Query event count
|
|
* _gfortran_caf_sync_all:: All-image barrier
|
|
* _gfortran_caf_sync_images:: Barrier for selected images
|
|
* _gfortran_caf_sync_memory:: Wait for completion of segment-memory operations
|
|
* _gfortran_caf_error_stop:: Error termination with exit code
|
|
* _gfortran_caf_error_stop_str:: Error termination with string
|
|
* _gfortran_caf_atomic_define:: Atomic variable assignment
|
|
* _gfortran_caf_atomic_ref:: Atomic variable reference
|
|
* _gfortran_caf_atomic_cas:: Atomic compare and swap
|
|
* _gfortran_caf_atomic_op:: Atomic operation
|
|
* _gfortran_caf_co_broadcast:: Sending data to all images
|
|
* _gfortran_caf_co_max:: Collective maximum reduction
|
|
* _gfortran_caf_co_min:: Collective minimum reduction
|
|
* _gfortran_caf_co_sum:: Collective summing reduction
|
|
* _gfortran_caf_co_reduce:: Generic collective reduction
|
|
@end menu
|
|
|
|
|
|
@node _gfortran_caf_init
|
|
@subsection @code{_gfortran_caf_init} --- Initialiation function
|
|
@cindex Coarray, _gfortran_caf_init
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
This function is called at startup of the program before the Fortran main
|
|
program, if the latter has been compiled with @option{-fcoarray=lib}.
|
|
It takes as arguments the command-line arguments of the program. It is
|
|
permitted to pass to @code{NULL} pointers as argument; if non-@code{NULL},
|
|
the library is permitted to modify the arguments.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_init (int *argc, char ***argv)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{argc} @tab intent(inout) An integer pointer with the number of
|
|
arguments passed to the program or @code{NULL}.
|
|
@item @var{argv} @tab intent(inout) A pointer to an array of strings with the
|
|
command-line arguments or @code{NULL}.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
The function is modelled after the initialization function of the Message
|
|
Passing Interface (MPI) specification. Due to the way coarray registration
|
|
works, it might not be the first call to the libaray. If the main program is
|
|
not written in Fortran and only a library uses coarrays, it can happen that
|
|
this function is never called. Therefore, it is recommended that the library
|
|
does not rely on the passed arguments and whether the call has been done.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_finish
|
|
@subsection @code{_gfortran_caf_finish} --- Finalization function
|
|
@cindex Coarray, _gfortran_caf_finish
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
This function is called at the end of the Fortran main program, if it has
|
|
been compiled with the @option{-fcoarray=lib} option.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_finish (void)}
|
|
|
|
@item @emph{NOTES}
|
|
For non-Fortran programs, it is recommended to call the function at the end
|
|
of the main program. To ensure that the shutdown is also performed for
|
|
programs where this function is not explicitly invoked, for instance
|
|
non-Fortran programs or calls to the system's exit() function, the library
|
|
can use a destructor function. Note that programs can also be terminated
|
|
using the STOP and ERROR STOP statements; those use different library calls.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_this_image
|
|
@subsection @code{_gfortran_caf_this_image} --- Querying the image number
|
|
@cindex Coarray, _gfortran_caf_this_image
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
This function returns the current image number, which is a positive number.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{int _gfortran_caf_this_image (int distance)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{distance} @tab As specified for the @code{this_image} intrinsic
|
|
in TS18508. Shall be a nonnegative number.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
If the Fortran intrinsic @code{this_image} is invoked without an argument, which
|
|
is the only permitted form in Fortran 2008, GCC passes @code{0} as
|
|
first argument.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_num_images
|
|
@subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images
|
|
@cindex Coarray, _gfortran_caf_num_images
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
This function returns the number of images in the current team, if
|
|
@var{distance} is 0 or the number of images in the parent team at the specified
|
|
distance. If failed is -1, the function returns the number of all images at
|
|
the specified distance; if it is 0, the function returns the number of
|
|
nonfailed images, and if it is 1, it returns the number of failed images.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{int _gfortran_caf_num_images(int distance, int failed)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{distance} @tab the distance from this image to the ancestor.
|
|
Shall be positive.
|
|
@item @var{failed} @tab shall be -1, 0, or 1
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
This function follows TS18508. If the num_image intrinsic has no arguments,
|
|
the the compiler passes @code{distance=0} and @code{failed=-1} to the function.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_register
|
|
@subsection @code{_gfortran_caf_register} --- Registering coarrays
|
|
@cindex Coarray, _gfortran_caf_register
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Registers memory for a coarray and creates a token to identify the coarray. The
|
|
routine is called for both coarrays with @code{SAVE} attribute and using an
|
|
explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a
|
|
@code{NULL} pointer, the function shall abort with printing an error message
|
|
and starting the error termination. If no error occurs and @var{STAT} is
|
|
present, it shall be set to zero. Otherwise, it shall be set to a positive
|
|
value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing
|
|
the failure. The routine shall register the memory provided in the
|
|
@code{DATA}-component of the array descriptor @var{DESC}, when that component
|
|
is non-@code{NULL}, else it shall allocate sufficient memory and provide a
|
|
pointer to it in the @code{DATA}-component of @var{DESC}. The array descriptor
|
|
has rank zero, when a scalar object is to be registered and the array
|
|
descriptor may be invalid after the call to @code{_gfortran_caf_register}.
|
|
When an array is to be allocated the descriptor persists.
|
|
|
|
For @code{CAF_REGTYPE_COARRAY_STATIC} and @code{CAF_REGTYPE_COARRAY_ALLOC},
|
|
the passed size is the byte size requested. For @code{CAF_REGTYPE_LOCK_STATIC},
|
|
@code{CAF_REGTYPE_LOCK_ALLOC} and @code{CAF_REGTYPE_CRITICAL} it is the array
|
|
size or one for a scalar.
|
|
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void caf_register (size_t size, caf_register_t type, caf_token_t *token,
|
|
gfc_descriptor_t *desc, int *stat, char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{size} @tab For normal coarrays, the byte size of the coarray to be
|
|
allocated; for lock types and event types, the number of elements.
|
|
@item @var{type} @tab one of the caf_register_t types.
|
|
@item @var{token} @tab intent(out) An opaque pointer identifying the coarray.
|
|
@item @var{desc} @tab intent(inout) The (pseudo) array descriptor.
|
|
@item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
|
|
may be NULL
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
Nonalloatable 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 nonallocatable coarrays the memory is allocated and no
|
|
static memory is used. The token permits to identify the coarray; to the
|
|
processor, the token is a nonaliasing pointer. The library can, for instance,
|
|
store the base address of the coarray in the token, some handle or a more
|
|
complicated struct. The library may also store the array descriptor
|
|
@var{DESC} when its rank is non-zero.
|
|
|
|
For lock types, the value shall only used for checking the allocation
|
|
status. Note that for critical blocks, the locking is only required on one
|
|
image; in the locking statement, the processor shall always pass an
|
|
image index of one for critical-block lock variables
|
|
(@code{CAF_REGTYPE_CRITICAL}). For lock types and critical-block variables,
|
|
the initial value shall be unlocked (or, respecitively, not in critical
|
|
section) such as the value false; for event types, the initial state should
|
|
be no event, e.g. zero.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_deregister
|
|
@subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays
|
|
@cindex Coarray, _gfortran_caf_deregister
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Called to free the memory of a coarray; the processor calls this function for
|
|
automatic and explicit deallocation. In case of an error, this function shall
|
|
fail with an error message, unless the @var{STAT} variable is not null. The
|
|
library is only expected to free memory it allocated itself during a call to
|
|
@code{_gfortran_caf_register}.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void caf_deregister (caf_token_t *token, caf_deregister_t type,
|
|
int *stat, char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab the token to free.
|
|
@item @var{type} @tab the type of action to take for the coarray. A
|
|
@code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} is allowed only for allocatable
|
|
components of derived type coarrays. The action only deallocates the local
|
|
memory without deleting the token.
|
|
@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set
|
|
to an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
For nonalloatable coarrays this function is never called. If a cleanup is
|
|
required, it has to be handled via the finish, stop and error stop functions,
|
|
and via destructors.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_is_present
|
|
@subsection @code{_gfortran_caf_is_present} --- Query whether an allocatable component in a derived type coarray is allocated
|
|
@cindex Coarray, _gfortran_caf_is_present
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Used to query the coarray library whether an allocatable component in a derived
|
|
type coarray is allocated on a remote image.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_is_present (caf_token_t token, int image_index,
|
|
gfc_reference_t *ref)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab An opaque pointer identifying the coarray.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number.
|
|
@item @var{ref} @tab A chain of references to address the allocatable component
|
|
in the derived type coarray. The object reffed needs to be a scalar or a full
|
|
array ref, respectively.
|
|
@end multitable
|
|
|
|
@end table
|
|
|
|
@node _gfortran_caf_send
|
|
@subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image
|
|
@cindex Coarray, _gfortran_caf_send
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Called to send a scalar, an array section or whole array from a local
|
|
to a remote image identified by the image_index.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_send (caf_token_t token, size_t offset,
|
|
int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
|
|
gfc_descriptor_t *src, int dst_kind, int src_kind, bool may_require_tmp)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{offset} @tab By which amount of bytes the actual data is shifted
|
|
compared to the base address of the coarray.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number.
|
|
@item @var{dest} @tab intent(in) Array descriptor for the remote image for the
|
|
bounds and the size. The base_addr shall not be accessed.
|
|
@item @var{dst_vector} @tab intent(in) If not NULL, it contains the vector
|
|
subscript of the destination array; the values are relative to the dimension
|
|
triplet of the dest argument.
|
|
@item @var{src} @tab intent(in) Array descriptor of the local array to be
|
|
transferred to the remote image
|
|
@item @var{dst_kind} @tab Kind of the destination argument
|
|
@item @var{src_kind} @tab Kind of the source argument
|
|
@item @var{may_require_tmp} @tab The variable is false it is known at compile
|
|
time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
|
|
or partially) such that walking @var{src} and @var{dest} in element wise
|
|
element order (honoring the stride value) will not lead to wrong results.
|
|
Otherwise, the value is true.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
It is permitted to have image_id equal the current image; the memory of the
|
|
send-to and the send-from might (partially) overlap in that case. The
|
|
implementation has to take care that it handles this case, e.g. using
|
|
@code{memmove} which handles (partially) overlapping memory. If
|
|
@var{may_require_tmp} is true, the library might additionally create a
|
|
temporary variable, unless additional checks show that this is not required
|
|
(e.g. because walking backward is possible or because both arrays are
|
|
contiguous and @code{memmove} takes care of overlap issues).
|
|
|
|
Note that the assignment of a scalar to an array is permitted. In addition,
|
|
the library has to handle numeric-type conversion and for strings, padding
|
|
and different character kinds.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_get
|
|
@subsection @code{_gfortran_caf_get} --- Getting data from a remote image
|
|
@cindex Coarray, _gfortran_caf_get
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Called to get an array section or whole array from a a remote,
|
|
image identified by the image_index.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_get (caf_token_t token, size_t offset,
|
|
int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector,
|
|
gfc_descriptor_t *dest, int src_kind, int dst_kind, bool may_require_tmp)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{offset} @tab By which amount of bytes the actual data is shifted
|
|
compared to the base address of the coarray.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number.
|
|
@item @var{dest} @tab intent(out) Array descriptor of the local array to store
|
|
the data transferred from the remote image
|
|
@item @var{src} @tab intent(in) Array descriptor for the remote image for the
|
|
bounds and the size. The base_addr shall not be accessed.
|
|
@item @var{src_vector} @tab intent(in) If not NULL, it contains the vector
|
|
subscript of the source array; the values are relative to the dimension
|
|
triplet of the src argument.
|
|
@item @var{dst_kind} @tab Kind of the destination argument
|
|
@item @var{src_kind} @tab Kind of the source argument
|
|
@item @var{may_require_tmp} @tab The variable is false it is known at compile
|
|
time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
|
|
or partially) such that walking @var{src} and @var{dest} in element wise
|
|
element order (honoring the stride value) will not lead to wrong results.
|
|
Otherwise, the value is true.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
It is permitted to have image_id equal the current image; the memory of the
|
|
send-to and the send-from might (partially) overlap in that case. The
|
|
implementation has to take care that it handles this case, e.g. using
|
|
@code{memmove} which handles (partially) overlapping memory. If
|
|
@var{may_require_tmp} is true, the library might additionally create a
|
|
temporary variable, unless additional checks show that this is not required
|
|
(e.g. because walking backward is possible or because both arrays are
|
|
contiguous and @code{memmove} takes care of overlap issues).
|
|
|
|
Note that the library has to handle numeric-type conversion and for strings,
|
|
padding and different character kinds.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_sendget
|
|
@subsection @code{_gfortran_caf_sendget} --- Sending data between remote images
|
|
@cindex Coarray, _gfortran_caf_sendget
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Called to send a scalar, an array section or whole array from a remote image
|
|
identified by the src_image_index to a remote image identified by the
|
|
dst_image_index.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset,
|
|
int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
|
|
caf_token_t src_token, size_t src_offset, int src_image_index,
|
|
gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind,
|
|
bool may_require_tmp)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{dst_token} @tab intent(in) An opaque pointer identifying the
|
|
destination coarray.
|
|
@item @var{dst_offset} @tab By which amount of bytes the actual data is
|
|
shifted compared to the base address of the destination coarray.
|
|
@item @var{dst_image_index} @tab The ID of the destination remote image; must
|
|
be a positive number.
|
|
@item @var{dest} @tab intent(in) Array descriptor for the destination
|
|
remote image for the bounds and the size. The base_addr shall not be accessed.
|
|
@item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
|
|
subscript of the destination array; the values are relative to the dimension
|
|
triplet of the dest argument.
|
|
@item @var{src_token} @tab An opaque pointer identifying the source coarray.
|
|
@item @var{src_offset} @tab By which amount of bytes the actual data is shifted
|
|
compared to the base address of the source coarray.
|
|
@item @var{src_image_index} @tab The ID of the source remote image; must be a
|
|
positive number.
|
|
@item @var{src} @tab intent(in) Array descriptor of the local array to be
|
|
transferred to the remote image.
|
|
@item @var{src_vector} @tab intent(in) Array descriptor of the local array to
|
|
be transferred to the remote image
|
|
@item @var{dst_kind} @tab Kind of the destination argument
|
|
@item @var{src_kind} @tab Kind of the source argument
|
|
@item @var{may_require_tmp} @tab The variable is false it is known at compile
|
|
time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
|
|
or partially) such that walking @var{src} and @var{dest} in element wise
|
|
element order (honoring the stride value) will not lead to wrong results.
|
|
Otherwise, the value is true.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
It is permitted to have image_ids equal; the memory of the send-to and the
|
|
send-from might (partially) overlap in that case. The implementation has to
|
|
take care that it handles this case, e.g. using @code{memmove} which handles
|
|
(partially) overlapping memory. If @var{may_require_tmp} is true, the library
|
|
might additionally create a temporary variable, unless additional checks show
|
|
that this is not required (e.g. because walking backward is possible or because
|
|
both arrays are contiguous and @code{memmove} takes care of overlap issues).
|
|
|
|
Note that the assignment of a scalar to an array is permitted. In addition,
|
|
the library has to handle numeric-type conversion and for strings, padding and
|
|
different character kinds.
|
|
@end table
|
|
|
|
@node _gfortran_caf_send_by_ref
|
|
@subsection @code{_gfortran_caf_send_by_ref} --- Sending data from a local image to a remote image with enhanced referencing options
|
|
@cindex Coarray, _gfortran_caf_send_by_ref
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Called to send a scalar, an array section or whole array from a local to a
|
|
remote image identified by the image_index.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_send_by_ref (caf_token_t token, int image_index,
|
|
gfc_descriptor_t *src, caf_reference_t *refs, int dst_kind, int src_kind,
|
|
bool may_require_tmp, bool dst_reallocatable, int *stat)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number.
|
|
@item @var{src} @tab intent(in) Array descriptor of the local array to be
|
|
transferred to the remote image
|
|
@item @var{refs} @tab intent(in) the references on the remote array to store
|
|
the data given by src. Guaranteed to have at least one entry.
|
|
@item @var{dst_kind} @tab Kind of the destination argument
|
|
@item @var{src_kind} @tab Kind of the source argument
|
|
@item @var{may_require_tmp} @tab The variable is false it is known at compile
|
|
time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
|
|
or partially) such that walking @var{src} and @var{dest} in element wise
|
|
element order (honoring the stride value) will not lead to wrong results.
|
|
Otherwise, the value is true.
|
|
@item @var{dst_reallocatable} @tab set when the destination is of allocatable
|
|
or pointer type and the refs will allow reallocation, i.e., the ref is a full
|
|
array or component ref.
|
|
@item @var{stat} @tab intent(out) when non-@code{NULL} give the result of the
|
|
operation, i.e., zero on success and non-zero on error. When @code{NULL} and
|
|
error occurs, then an error message is printed and the program is terminated.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
It is permitted to have image_id equal the current image; the memory of the
|
|
send-to and the send-from might (partially) overlap in that case. The
|
|
implementation has to take care that it handles this case, e.g. using
|
|
@code{memmove} which handles (partially) overlapping memory. If
|
|
@var{may_require_tmp} is true, the library might additionally create a
|
|
temporary variable, unless additional checks show that this is not required
|
|
(e.g. because walking backward is possible or because both arrays are
|
|
contiguous and @code{memmove} takes care of overlap issues).
|
|
|
|
Note that the assignment of a scalar to an array is permitted. In addition,
|
|
the library has to handle numeric-type conversion and for strings, padding
|
|
and different character kinds.
|
|
|
|
Because of the more complicated references possible some operations may be
|
|
unsupported by certain libraries. The library is expected to issue a precise
|
|
error message why the operation is not permitted.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_get_by_ref
|
|
@subsection @code{_gfortran_caf_get_by_ref} --- Getting data from a remote image using enhanced references
|
|
@cindex Coarray, _gfortran_caf_get_by_ref
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Called to get a scalar, an array section or whole array from a a remote image
|
|
identified by the image_index.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_get_by_ref (caf_token_t token, int image_index,
|
|
caf_reference_t *refs, gfc_descriptor_t *dst, int dst_kind, int src_kind,
|
|
bool may_require_tmp, bool dst_reallocatable, int *stat)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number.
|
|
@item @var{refs} @tab intent(in) the references to apply to the remote structure
|
|
to get the data.
|
|
@item @var{dst} @tab intent(in) Array descriptor of the local array to store
|
|
the data transferred from the remote image. May be reallocated where needed
|
|
and when @var{DST_REALLOCATABLE} allows it.
|
|
@item @var{dst_kind} @tab Kind of the destination argument
|
|
@item @var{src_kind} @tab Kind of the source argument
|
|
@item @var{may_require_tmp} @tab The variable is false it is known at compile
|
|
time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
|
|
or partially) such that walking @var{src} and @var{dest} in element wise
|
|
element order (honoring the stride value) will not lead to wrong results.
|
|
Otherwise, the value is true.
|
|
@item @var{dst_reallocatable} @tab set when @var{DST} is of allocatable
|
|
or pointer type and its refs allow reallocation, i.e., the full array or a
|
|
component is referenced.
|
|
@item @var{stat} @tab intent(out) when non-@code{NULL} give the result of the
|
|
operation, i.e., zero on success and non-zero on error. When @code{NULL} and
|
|
error occurs, then an error message is printed and the program is terminated.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
It is permitted to have image_id equal the current image; the memory of the
|
|
send-to and the send-from might (partially) overlap in that case. The
|
|
implementation has to take care that it handles this case, e.g. using
|
|
@code{memmove} which handles (partially) overlapping memory. If
|
|
@var{may_require_tmp} is true, the library might additionally create a
|
|
temporary variable, unless additional checks show that this is not required
|
|
(e.g. because walking backward is possible or because both arrays are
|
|
contiguous and @code{memmove} takes care of overlap issues).
|
|
|
|
Note that the library has to handle numeric-type conversion and for strings,
|
|
padding and different character kinds.
|
|
|
|
Because of the more complicated references possible some operations may be
|
|
unsupported by certain libraries. The library is expected to issue a precise
|
|
error message why the operation is not permitted.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_sendget_by_ref
|
|
@subsection @code{_gfortran_caf_sendget_by_ref} --- Sending data between remote images using enhanced references on both sides
|
|
@cindex Coarray, _gfortran_caf_sendget_by_ref
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Called to send a scalar, an array section or whole array from a remote image
|
|
identified by the src_image_index to a remote image identified by the
|
|
dst_image_index.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_sendget_by_ref (caf_token_t dst_token,
|
|
int dst_image_index, caf_reference_t *dst_refs,
|
|
caf_token_t src_token, int src_image_index, caf_reference_t *src_refs,
|
|
int dst_kind, int src_kind, bool may_require_tmp, int *dst_stat, int *src_stat)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{dst_token} @tab intent(in) An opaque pointer identifying the
|
|
destination coarray.
|
|
@item @var{dst_image_index} @tab The ID of the destination remote image; must
|
|
be a positive number.
|
|
@item @var{dst_refs} @tab intent(in) the references on the remote array to store
|
|
the data given by src. Guaranteed to have at least one entry.
|
|
@item @var{src_token} @tab An opaque pointer identifying the source coarray.
|
|
@item @var{src_image_index} @tab The ID of the source remote image; must be a
|
|
positive number.
|
|
@item @var{src_refs} @tab intent(in) the references to apply to the remote
|
|
structure to get the data.
|
|
@item @var{dst_kind} @tab Kind of the destination argument
|
|
@item @var{src_kind} @tab Kind of the source argument
|
|
@item @var{may_require_tmp} @tab The variable is false it is known at compile
|
|
time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
|
|
or partially) such that walking @var{src} and @var{dest} in element wise
|
|
element order (honoring the stride value) will not lead to wrong results.
|
|
Otherwise, the value is true.
|
|
@item @var{dst_stat} @tab intent(out) when non-@code{NULL} give the result of
|
|
the send-operation, i.e., zero on success and non-zero on error. When
|
|
@code{NULL} and an error occurs, then an error message is printed and the
|
|
program is terminated.
|
|
@item @var{src_stat} @tab intent(out) when non-@code{NULL} give the result of
|
|
the get-operation, i.e., zero on success and non-zero on error. When
|
|
@code{NULL} and an error occurs, then an error message is printed and the
|
|
program is terminated.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
It is permitted to have image_ids equal; the memory of the send-to and the
|
|
send-from might (partially) overlap in that case. The implementation has to
|
|
take care that it handles this case, e.g. using @code{memmove} which handles
|
|
(partially) overlapping memory. If @var{may_require_tmp} is true, the library
|
|
might additionally create a temporary variable, unless additional checks show
|
|
that this is not required (e.g. because walking backward is possible or because
|
|
both arrays are contiguous and @code{memmove} takes care of overlap issues).
|
|
|
|
Note that the assignment of a scalar to an array is permitted. In addition,
|
|
the library has to handle numeric-type conversion and for strings, padding and
|
|
different character kinds.
|
|
|
|
Because of the more complicated references possible some operations may be
|
|
unsupported by certain libraries. The library is expected to issue a precise
|
|
error message why the operation is not permitted.
|
|
@end table
|
|
|
|
|
|
@node _gfortran_caf_lock
|
|
@subsection @code{_gfortran_caf_lock} --- Locking a lock variable
|
|
@cindex Coarray, _gfortran_caf_lock
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Acquire a lock on the given image on a scalar locking variable or for the
|
|
given array element for an array-valued variable. If the @var{aquired_lock}
|
|
is @code{NULL}, the function return after having obtained the lock. If it is
|
|
nonnull, the result is is assigned the value true (one) when the lock could be
|
|
obtained and false (zero) otherwise. Locking a lock variable which has already
|
|
been locked by the same image is an error.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_lock (caf_token_t token, size_t index, int image_index,
|
|
int *aquired_lock, int *stat, char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{index} @tab Array index; first array index is 0. For scalars, it is
|
|
always 0.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number.
|
|
@item @var{aquired_lock} @tab intent(out) If not NULL, it returns whether lock
|
|
could be obtained
|
|
@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
This function is also called for critical blocks; for those, the array index
|
|
is always zero and the image index is one. Libraries are permitted to use other
|
|
images for critical-block locking variables.
|
|
@end table
|
|
|
|
@node _gfortran_caf_unlock
|
|
@subsection @code{_gfortran_caf_lock} --- Unlocking a lock variable
|
|
@cindex Coarray, _gfortran_caf_unlock
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Release a lock on the given image on a scalar locking variable or for the
|
|
given array element for an array-valued variable. Unlocking a lock variable
|
|
which is unlocked or has been locked by a different image is an error.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_unlock (caf_token_t token, size_t index, int image_index,
|
|
int *stat, char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{index} @tab Array index; first array index is 0. For scalars, it is
|
|
always 0.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number.
|
|
@item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
|
|
may be NULL
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
This function is also called for critical block; for those, the array index
|
|
is always zero and the image index is one. Libraries are permitted to use other
|
|
images for critical-block locking variables.
|
|
@end table
|
|
|
|
@node _gfortran_caf_event_post
|
|
@subsection @code{_gfortran_caf_event_post} --- Post an event
|
|
@cindex Coarray, _gfortran_caf_event_post
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Increment the event count of the specified event variable.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_event_post (caf_token_t token, size_t index,
|
|
int image_index, int *stat, char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{index} @tab Array index; first array index is 0. For scalars, it is
|
|
always 0.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number; zero indicates the current image when accessed noncoindexed.
|
|
@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
This acts like an atomic add of one to the remote image's event variable.
|
|
The statement is an image-control statement but does not imply sync memory.
|
|
Still, all preceeding push communications of this image to the specified
|
|
remote image has to be completed before @code{event_wait} on the remote
|
|
image returns.
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_event_wait
|
|
@subsection @code{_gfortran_caf_event_wait} --- Wait that an event occurred
|
|
@cindex Coarray, _gfortran_caf_event_wait
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Wait until the event count has reached at least the specified
|
|
@var{until_count}; if so, atomically decrement the event variable by this
|
|
amount and return.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_event_wait (caf_token_t token, size_t index,
|
|
int until_count, int *stat, char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{index} @tab Array index; first array index is 0. For scalars, it is
|
|
always 0.
|
|
@item @var{until_count} @tab The number of events which have to be available
|
|
before the function returns.
|
|
@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
This function only operates on a local coarray. It acts like a loop checking
|
|
atomically the value of the event variable, breaking if the value is greater
|
|
or equal the requested number of counts. Before the function returns, the
|
|
event variable has to be decremented by the requested @var{until_count} value.
|
|
A possible implementation would be a busy loop for a certain number of spins
|
|
(possibly depending on the number of threads relative to the number of available
|
|
cores) followed by other 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 to this image of images having
|
|
issued a @code{event_push} have to be completed before this function returns.
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_event_query
|
|
@subsection @code{_gfortran_caf_event_query} --- Query event count
|
|
@cindex Coarray, _gfortran_caf_event_query
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Return the event count of the specified event count.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_event_query (caf_token_t token, size_t index,
|
|
int image_index, int *count, int *stat)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{index} @tab Array index; first array index is 0. For scalars, it is
|
|
always 0.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number; zero indicates the current image when accessed noncoindexed.
|
|
@item @var{count} @tab intent(out) The number of events currently posted to
|
|
the event variable
|
|
@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
The typical use is to check the local even variable to only call
|
|
@code{event_wait} when the data is available. However, a coindexed variable
|
|
is permitted; there is no ordering or synchronization implied. It acts like
|
|
an atomic fetch of the value of the event variable.
|
|
@end table
|
|
|
|
@node _gfortran_caf_sync_all
|
|
@subsection @code{_gfortran_caf_sync_all} --- All-image barrier
|
|
@cindex Coarray, _gfortran_caf_sync_all
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Synchronization of all images in the current team; the program only continues
|
|
on a given image after this function has been called on all images of the
|
|
current team. Additionally, it ensures that all pending data transfers of
|
|
previous segment have completed.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_sync_all (int *stat, char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_sync_images
|
|
@subsection @code{_gfortran_caf_sync_images} --- Barrier for selected images
|
|
@cindex Coarray, _gfortran_caf_sync_images
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Synchronization between the specified images; the program only continues on a
|
|
given image after this function has been called on all images specified for
|
|
that image. Note that one image can wait for all other images in the current
|
|
team (e.g. via @code{sync images(*)}) while those only wait for that specific
|
|
image. Additionally, @code{sync images} it ensures that all pending data
|
|
transfers of previous segment have completed.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_sync_images (int count, int images[], int *stat,
|
|
char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{count} @tab the number of images which are provided in the next
|
|
argument. For a zero-sized array, the value is zero. For @code{sync
|
|
images (*)}, the value is @math{-1}.
|
|
@item @var{images} @tab intent(in) an array with the images provided by the
|
|
user. If @var{count} is zero, a NULL pointer is passed.
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_sync_memory
|
|
@subsection @code{_gfortran_caf_sync_memory} --- Wait for completion of segment-memory operations
|
|
@cindex Coarray, _gfortran_caf_sync_memory
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Acts as optimization barrier between different segments. It also ensures that
|
|
all pending memory operations of this image have been completed.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_sync_memory (int *stat, char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTE} A simple implementation could be
|
|
@code{__asm__ __volatile__ ("":::"memory")} to prevent code movements.
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_error_stop
|
|
@subsection @code{_gfortran_caf_error_stop} --- Error termination with exit code
|
|
@cindex Coarray, _gfortran_caf_error_stop
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Invoked for an @code{ERROR STOP} statement which has an integer argument. The
|
|
function should terminate the program with the specified exit code.
|
|
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_error_stop (int32_t error)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{error} @tab the exit status to be used.
|
|
@end multitable
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_error_stop_str
|
|
@subsection @code{_gfortran_caf_error_stop_str} --- Error termination with string
|
|
@cindex Coarray, _gfortran_caf_error_stop_str
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Invoked for an @code{ERROR STOP} statement which has a string as argument. The
|
|
function should terminate the program with a nonzero-exit code.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_error_stop (const char *string, int32_t len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{string} @tab the error message (not zero terminated)
|
|
@item @var{len} @tab the length of the string
|
|
@end multitable
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_atomic_define
|
|
@subsection @code{_gfortran_caf_atomic_define} --- Atomic variable assignment
|
|
@cindex Coarray, _gfortran_caf_atomic_define
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Assign atomically a value to an integer or logical variable.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_atomic_define (caf_token_t token, size_t offset,
|
|
int image_index, void *value, int *stat, int type, int kind)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{offset} @tab By which amount of bytes the actual data is shifted
|
|
compared to the base address of the coarray.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number; zero indicates the current image when used noncoindexed.
|
|
@item @var{value} @tab intent(in) the value to be assigned, passed by reference.
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
|
|
@code{BT_LOGICAL} (2).
|
|
@item @var{kind} @tab The kind value (only 4; always @code{int})
|
|
@end multitable
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_atomic_ref
|
|
@subsection @code{_gfortran_caf_atomic_ref} --- Atomic variable reference
|
|
@cindex Coarray, _gfortran_caf_atomic_ref
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Reference atomically a value of a kind-4 integer or logical variable.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_atomic_ref (caf_token_t token, size_t offset,
|
|
int image_index, void *value, int *stat, int type, int kind)}
|
|
|
|
@item @emph{Arguments}:
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{offset} @tab By which amount of bytes the actual data is shifted
|
|
compared to the base address of the coarray.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number; zero indicates the current image when used noncoindexed.
|
|
@item @var{value} @tab intent(out) The variable assigned the atomically
|
|
referenced variable.
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
|
|
@code{BT_LOGICAL} (2).
|
|
@item @var{kind} @tab The kind value (only 4; always @code{int})
|
|
@end multitable
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_atomic_cas
|
|
@subsection @code{_gfortran_caf_atomic_cas} --- Atomic compare and swap
|
|
@cindex Coarray, _gfortran_caf_atomic_cas
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Atomic compare and swap of a kind-4 integer or logical variable. Assigns
|
|
atomically the specified value to the atomic variable, if the latter has
|
|
the value specified by the passed condition value.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_atomic_cas (caf_token_t token, size_t offset,
|
|
int image_index, void *old, void *compare, void *new_val, int *stat,
|
|
int type, int kind)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{offset} @tab By which amount of bytes the actual data is shifted
|
|
compared to the base address of the coarray.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number; zero indicates the current image when used noncoindexed.
|
|
@item @var{old} @tab intent(out) the value which the atomic variable had
|
|
just before the cas operation.
|
|
@item @var{compare} @tab intent(in) The value used for comparision.
|
|
@item @var{new_val} @tab intent(in) The new value for the atomic variable,
|
|
assigned to the atomic variable, if @code{compare} equals the value of the
|
|
atomic variable.
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
|
|
@code{BT_LOGICAL} (2).
|
|
@item @var{kind} @tab The kind value (only 4; always @code{int})
|
|
@end multitable
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_atomic_op
|
|
@subsection @code{_gfortran_caf_atomic_op} --- Atomic operation
|
|
@cindex Coarray, _gfortran_caf_atomic_op
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Apply an operation atomically to an atomic integer or logical variable.
|
|
After the operation, @var{old} contains the value just before the operation,
|
|
which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the @code{value} to
|
|
the atomic integer variable or does a bitwise AND, OR or exclusive OR of the
|
|
between the atomic variable and @var{value}; the result is then stored in the
|
|
atomic variable.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_atomic_op (int op, caf_token_t token, size_t offset,
|
|
int image_index, void *value, void *old, int *stat, int type, int kind)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{op} @tab the operation to be performed; possible values
|
|
@code{GFC_CAF_ATOMIC_ADD} (1), @code{GFC_CAF_ATOMIC_AND} (2),
|
|
@code{GFC_CAF_ATOMIC_OR} (3), @code{GFC_CAF_ATOMIC_XOR} (4).
|
|
@item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
|
|
@item @var{offset} @tab By which amount of bytes the actual data is shifted
|
|
compared to the base address of the coarray.
|
|
@item @var{image_index} @tab The ID of the remote image; must be a positive
|
|
number; zero indicates the current image when used noncoindexed.
|
|
@item @var{old} @tab intent(out) the value which the atomic variable had
|
|
just before the atomic operation.
|
|
@item @var{val} @tab intent(in) The new value for the atomic variable,
|
|
assigned to the atomic variable, if @code{compare} equals the value of the
|
|
atomic variable.
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
|
|
@code{BT_LOGICAL} (2).
|
|
@item @var{kind} @tab The kind value (only 4; always @code{int})
|
|
@end multitable
|
|
@end table
|
|
|
|
|
|
|
|
|
|
@node _gfortran_caf_co_broadcast
|
|
@subsection @code{_gfortran_caf_co_broadcast} --- Sending data to all images
|
|
@cindex Coarray, _gfortran_caf_co_broadcast
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Distribute a value from a given image to all other images in the team. Has to
|
|
be called collectively.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_co_broadcast (gfc_descriptor_t *a,
|
|
int source_image, int *stat, char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{a} @tab intent(inout) And array descriptor with the data to be
|
|
breoadcasted (on @var{source_image}) or to be received (other images).
|
|
@item @var{source_image} @tab The ID of the image from which the data should
|
|
be taken.
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_co_max
|
|
@subsection @code{_gfortran_caf_co_max} --- Collective maximum reduction
|
|
@cindex Coarray, _gfortran_caf_co_max
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Calculates the for the each array element of the variable @var{a} the maximum
|
|
value for that element in the current team; if @var{result_image} has the
|
|
value 0, the result shall be stored on all images, otherwise, only on the
|
|
specified image. This function operates on numeric values and character
|
|
strings.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_co_max (gfc_descriptor_t *a, int result_image,
|
|
int *stat, char *errmsg, int a_len, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{a} @tab intent(inout) And array descriptor with the data to be
|
|
breoadcasted (on @var{source_image}) or to be received (other images).
|
|
@item @var{result_image} @tab The ID of the image to which the reduced
|
|
value should be copied to; if zero, it has to be copied to all images.
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{a_len} @tab The string length of argument @var{a}.
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
If @var{result_image} is nonzero, the value on all images except of the
|
|
specified one become undefined; hence, the library may make use of this.
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_co_min
|
|
@subsection @code{_gfortran_caf_co_min} --- Collective minimum reduction
|
|
@cindex Coarray, _gfortran_caf_co_min
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Calculates the for the each array element of the variable @var{a} the minimum
|
|
value for that element in the current team; if @var{result_image} has the
|
|
value 0, the result shall be stored on all images, otherwise, only on the
|
|
specified image. This function operates on numeric values and character
|
|
strings.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_co_min (gfc_descriptor_t *a, int result_image,
|
|
int *stat, char *errmsg, int a_len, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{a} @tab intent(inout) And array descriptor with the data to be
|
|
breoadcasted (on @var{source_image}) or to be received (other images).
|
|
@item @var{result_image} @tab The ID of the image to which the reduced
|
|
value should be copied to; if zero, it has to be copied to all images.
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{a_len} @tab The string length of argument @var{a}.
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
If @var{result_image} is nonzero, the value on all images except of the
|
|
specified one become undefined; hence, the library may make use of this.
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_co_sum
|
|
@subsection @code{_gfortran_caf_co_sum} --- Collective summing reduction
|
|
@cindex Coarray, _gfortran_caf_co_sum
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Calculates the for the each array element of the variable @var{a} the sum
|
|
value for that element in the current team; if @var{result_image} has the
|
|
value 0, the result shall be stored on all images, otherwise, only on the
|
|
specified image. This function operates on numeric values.
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_co_sum (gfc_descriptor_t *a, int result_image,
|
|
int *stat, char *errmsg, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{a} @tab intent(inout) And array descriptor with the data to be
|
|
breoadcasted (on @var{source_image}) or to be received (other images).
|
|
@item @var{result_image} @tab The ID of the image to which the reduced
|
|
value should be copied to; if zero, it has to be copied to all images.
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
If @var{result_image} is nonzero, the value on all images except of the
|
|
specified one become undefined; hence, the library may make use of this.
|
|
@end table
|
|
|
|
|
|
|
|
@node _gfortran_caf_co_reduce
|
|
@subsection @code{_gfortran_caf_co_reduce} --- Generic collective reduction
|
|
@cindex Coarray, _gfortran_caf_co_reduce
|
|
|
|
@table @asis
|
|
@item @emph{Description}:
|
|
Calculates the for the each array element of the variable @var{a} the reduction
|
|
value for that element in the current team; if @var{result_image} has the
|
|
value 0, the result shall be stored on all images, otherwise, only on the
|
|
specified image. The @var{opr} is a pure function doing a mathematically
|
|
commutative and associative operation.
|
|
|
|
The @var{opr_flags} denote the following; the values are bitwise ored.
|
|
@code{GFC_CAF_BYREF} (1) if the result should be returned
|
|
by value; @code{GFC_CAF_HIDDENLEN} (2) whether the result and argument
|
|
string lengths shall be specified as hidden argument;
|
|
@code{GFC_CAF_ARG_VALUE} (4) whether the arguments shall be passed by value,
|
|
@code{GFC_CAF_ARG_DESC} (8) whether the arguments shall be passed by descriptor.
|
|
|
|
|
|
@item @emph{Syntax}:
|
|
@code{void _gfortran_caf_co_reduce (gfc_descriptor_t *a,
|
|
void * (*opr) (void *, void *), int opr_flags, int result_image,
|
|
int *stat, char *errmsg, int a_len, int errmsg_len)}
|
|
|
|
@item @emph{Arguments}:
|
|
@multitable @columnfractions .15 .70
|
|
@item @var{opr} @tab Function pointer to the reduction function.
|
|
@item @var{opr_flags} @tab Flags regarding the reduction function
|
|
@item @var{a} @tab intent(inout) And array descriptor with the data to be
|
|
breoadcasted (on @var{source_image}) or to be received (other images).
|
|
@item @var{result_image} @tab The ID of the image to which the reduced
|
|
value should be copied to; if zero, it has to be copied to all images.
|
|
@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
|
|
@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
|
|
an error message; may be NULL
|
|
@item @var{a_len} @tab The string length of argument @var{a}.
|
|
@item @var{errmsg_len} @tab the buffer size of errmsg.
|
|
@end multitable
|
|
|
|
@item @emph{NOTES}
|
|
If @var{result_image} is nonzero, the value 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 arguments. With C binding, there are no hidden arguments
|
|
and by-reference passing and either only a single character is passed or
|
|
an array descriptor.
|
|
@end table
|
|
|
|
|
|
@c Intrinsic Procedures
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@include intrinsic.texi
|
|
|
|
|
|
@tex
|
|
\blankpart
|
|
@end tex
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Contributing
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Contributing
|
|
@unnumbered Contributing
|
|
@cindex Contributing
|
|
|
|
Free software is only possible if people contribute to efforts
|
|
to create it.
|
|
We're always in need of more people helping out with ideas
|
|
and comments, writing documentation and contributing code.
|
|
|
|
If you want to contribute to GNU Fortran,
|
|
have a look at the long lists of projects you can take on.
|
|
Some of these projects are small,
|
|
some of them are large;
|
|
some are completely orthogonal to the rest of what is
|
|
happening on GNU Fortran,
|
|
but others are ``mainstream'' projects in need of enthusiastic hackers.
|
|
All of these projects are important!
|
|
We will eventually get around to the things here,
|
|
but they are also things doable by someone who is willing and able.
|
|
|
|
@menu
|
|
* Contributors::
|
|
* Projects::
|
|
* Proposed Extensions::
|
|
@end menu
|
|
|
|
|
|
@node Contributors
|
|
@section Contributors to GNU Fortran
|
|
@cindex Contributors
|
|
@cindex Credits
|
|
@cindex Authors
|
|
|
|
Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
|
|
also the initiator of the whole project. Thanks Andy!
|
|
Most of the interface with GCC was written by @emph{Paul Brook}.
|
|
|
|
The following individuals have contributed code and/or
|
|
ideas and significant help to the GNU Fortran project
|
|
(in alphabetical order):
|
|
|
|
@itemize @minus
|
|
@item Janne Blomqvist
|
|
@item Steven Bosscher
|
|
@item Paul Brook
|
|
@item Tobias Burnus
|
|
@item Fran@,{c}ois-Xavier Coudert
|
|
@item Bud Davis
|
|
@item Jerry DeLisle
|
|
@item Erik Edelmann
|
|
@item Bernhard Fischer
|
|
@item Daniel Franke
|
|
@item Richard Guenther
|
|
@item Richard Henderson
|
|
@item Katherine Holcomb
|
|
@item Jakub Jelinek
|
|
@item Niels Kristian Bech Jensen
|
|
@item Steven Johnson
|
|
@item Steven G. Kargl
|
|
@item Thomas Koenig
|
|
@item Asher Langton
|
|
@item H. J. Lu
|
|
@item Toon Moene
|
|
@item Brooks Moses
|
|
@item Andrew Pinski
|
|
@item Tim Prince
|
|
@item Christopher D. Rickett
|
|
@item Richard Sandiford
|
|
@item Tobias Schl@"uter
|
|
@item Roger Sayle
|
|
@item Paul Thomas
|
|
@item Andy Vaught
|
|
@item Feng Wang
|
|
@item Janus Weil
|
|
@item Daniel Kraft
|
|
@end itemize
|
|
|
|
The following people have contributed bug reports,
|
|
smaller or larger patches,
|
|
and much needed feedback and encouragement for the
|
|
GNU Fortran project:
|
|
|
|
@itemize @minus
|
|
@item Bill Clodius
|
|
@item Dominique d'Humi@`eres
|
|
@item Kate Hedstrom
|
|
@item Erik Schnetter
|
|
@item Joost VandeVondele
|
|
@end itemize
|
|
|
|
Many other individuals have helped debug,
|
|
test and improve the GNU Fortran compiler over the past few years,
|
|
and we welcome you to do the same!
|
|
If you already have done so,
|
|
and you would like to see your name listed in the
|
|
list above, please contact us.
|
|
|
|
|
|
@node Projects
|
|
@section Projects
|
|
|
|
@table @emph
|
|
|
|
@item Help build the test suite
|
|
Solicit more code for donation to the test suite: the more extensive the
|
|
testsuite, the smaller the risk of breaking things in the future! We can
|
|
keep code private on request.
|
|
|
|
@item Bug hunting/squishing
|
|
Find bugs and write more test cases! Test cases are especially very
|
|
welcome, because it allows us to concentrate on fixing bugs instead of
|
|
isolating them. Going through the bugzilla database at
|
|
@url{https://gcc.gnu.org/@/bugzilla/} to reduce testcases posted there and
|
|
add more information (for example, for which version does the testcase
|
|
work, for which versions does it fail?) is also very helpful.
|
|
|
|
@end table
|
|
|
|
|
|
@node Proposed Extensions
|
|
@section Proposed Extensions
|
|
|
|
Here's a list of proposed extensions for the GNU Fortran compiler, in no particular
|
|
order. Most of these are necessary to be fully compatible with
|
|
existing Fortran compilers, but they are not part of the official
|
|
J3 Fortran 95 standard.
|
|
|
|
@subsection Compiler extensions:
|
|
@itemize @bullet
|
|
@item
|
|
User-specified alignment rules for structures.
|
|
|
|
@item
|
|
Automatically extend single precision constants to double.
|
|
|
|
@item
|
|
Compile code that conserves memory by dynamically allocating common and
|
|
module storage either on stack or heap.
|
|
|
|
@item
|
|
Compile flag to generate code for array conformance checking (suggest -CC).
|
|
|
|
@item
|
|
User control of symbol names (underscores, etc).
|
|
|
|
@item
|
|
Compile setting for maximum size of stack frame size before spilling
|
|
parts to static or heap.
|
|
|
|
@item
|
|
Flag to force local variables into static space.
|
|
|
|
@item
|
|
Flag to force local variables onto stack.
|
|
@end itemize
|
|
|
|
|
|
@subsection Environment Options
|
|
@itemize @bullet
|
|
@item
|
|
Pluggable library modules for random numbers, linear algebra.
|
|
LA should use BLAS calling conventions.
|
|
|
|
@item
|
|
Environment variables controlling actions on arithmetic exceptions like
|
|
overflow, underflow, precision loss---Generate NaN, abort, default.
|
|
action.
|
|
|
|
@item
|
|
Set precision for fp units that support it (i387).
|
|
|
|
@item
|
|
Variable for setting fp rounding mode.
|
|
|
|
@item
|
|
Variable to fill uninitialized variables with a user-defined bit
|
|
pattern.
|
|
|
|
@item
|
|
Environment variable controlling filename that is opened for that unit
|
|
number.
|
|
|
|
@item
|
|
Environment variable to clear/trash memory being freed.
|
|
|
|
@item
|
|
Environment variable to control tracing of allocations and frees.
|
|
|
|
@item
|
|
Environment variable to display allocated memory at normal program end.
|
|
|
|
@item
|
|
Environment variable for filename for * IO-unit.
|
|
|
|
@item
|
|
Environment variable for temporary file directory.
|
|
|
|
@item
|
|
Environment variable forcing standard output to be line buffered (Unix).
|
|
|
|
@end itemize
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c GNU General Public License
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@include gpl_v3.texi
|
|
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c GNU Free Documentation License
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@include fdl.texi
|
|
|
|
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Funding Free Software
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@include funding.texi
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@c Indices
|
|
@c ---------------------------------------------------------------------
|
|
|
|
@node Option Index
|
|
@unnumbered Option Index
|
|
@command{gfortran}'s command line options are indexed here without any
|
|
initial @samp{-} or @samp{--}. Where an option has both positive and
|
|
negative forms (such as -foption and -fno-option), relevant entries in
|
|
the manual are indexed under the most appropriate form; it may sometimes
|
|
be useful to look up both forms.
|
|
@printindex op
|
|
|
|
@node Keyword Index
|
|
@unnumbered Keyword Index
|
|
@printindex cp
|
|
|
|
@bye
|