| \input texinfo @c -*-texinfo-*- |
| @c %**start of header |
| @setfilename gfortran.info |
| @set copyrights-gfortran 1999-2022 |
| |
| @include gcc-common.texi |
| |
| @settitle The GNU Fortran Compiler |
| |
| @c Create a separate index for command line options |
| @defcodeindex op |
| @c Merge the standard indexes into a single one. |
| @syncodeindex fn cp |
| @syncodeindex vr cp |
| @syncodeindex ky cp |
| @syncodeindex pg cp |
| @syncodeindex tp cp |
| |
| @c TODO: The following "Part" definitions are included here temporarily |
| @c until they are incorporated into the official Texinfo distribution. |
| @c They borrow heavily from Texinfo's \unnchapentry definitions. |
| |
| @tex |
| \gdef\part#1#2{% |
| \pchapsepmacro |
| \gdef\thischapter{} |
| \begingroup |
| \vglue\titlepagetopglue |
| \titlefonts \rm |
| \leftline{Part #1:@* #2} |
| \vskip4pt \hrule height 4pt width \hsize \vskip4pt |
| \endgroup |
| \writetocentry{part}{#2}{#1} |
| } |
| \gdef\blankpart{% |
| \writetocentry{blankpart}{}{} |
| } |
| % Part TOC-entry definition for summary contents. |
| \gdef\dosmallpartentry#1#2#3#4{% |
| \vskip .5\baselineskip plus.2\baselineskip |
| \begingroup |
| \let\rm=\bf \rm |
| \tocentry{Part #2: #1}{\doshortpageno\bgroup#4\egroup} |
| \endgroup |
| } |
| \gdef\dosmallblankpartentry#1#2#3#4{% |
| \vskip .5\baselineskip plus.2\baselineskip |
| } |
| % Part TOC-entry definition for regular contents. This has to be |
| % equated to an existing entry to not cause problems when the PDF |
| % outline is created. |
| \gdef\dopartentry#1#2#3#4{% |
| \unnchapentry{Part #2: #1}{}{#3}{#4} |
| } |
| \gdef\doblankpartentry#1#2#3#4{} |
| @end tex |
| |
| @c %**end of header |
| |
| @c Use with @@smallbook. |
| |
| @c %** start of document |
| |
| @c Cause even numbered pages to be printed on the left hand side of |
| @c the page and odd numbered pages to be printed on the right hand |
| @c side of the page. Using this, you can print on both sides of a |
| @c sheet of paper and have the text on the same part of the sheet. |
| |
| @c The text on right hand pages is pushed towards the right hand |
| @c margin and the text on left hand pages is pushed toward the left |
| @c hand margin. |
| @c (To provide the reverse effect, set bindingoffset to -0.75in.) |
| |
| @c @tex |
| @c \global\bindingoffset=0.75in |
| @c \global\normaloffset =0.75in |
| @c @end tex |
| |
| @copying |
| Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Funding Free Software'', the Front-Cover |
| Texts being (a) (see below), and with the Back-Cover Texts being (b) |
| (see below). A copy of the license is included in the section entitled |
| ``GNU Free Documentation License''. |
| |
| (a) The FSF's Front-Cover Text is: |
| |
| A GNU Manual |
| |
| (b) The FSF's Back-Cover Text is: |
| |
| You have freedom to copy and modify this GNU Manual, like GNU |
| software. Copies published by the Free Software Foundation raise |
| funds for GNU development. |
| @end copying |
| |
| @ifinfo |
| @dircategory Software development |
| @direntry |
| * gfortran: (gfortran). The GNU Fortran Compiler. |
| @end direntry |
| This file documents the use and the internals of |
| the GNU Fortran compiler, (@command{gfortran}). |
| |
| Published by the Free Software Foundation |
| 51 Franklin Street, Fifth Floor |
| Boston, MA 02110-1301 USA |
| |
| @insertcopying |
| @end ifinfo |
| |
| |
| @setchapternewpage odd |
| @titlepage |
| @title Using GNU Fortran |
| @versionsubtitle |
| @author The @t{gfortran} team |
| @page |
| @vskip 0pt plus 1filll |
| Published by the Free Software Foundation@* |
| 51 Franklin Street, Fifth Floor@* |
| Boston, MA 02110-1301, USA@* |
| @c Last printed ??ber, 19??.@* |
| @c Printed copies are available for $? each.@* |
| @c ISBN ??? |
| @sp 1 |
| @insertcopying |
| @end titlepage |
| |
| @c TODO: The following "Part" definitions are included here temporarily |
| @c until they are incorporated into the official Texinfo distribution. |
| |
| @tex |
| \global\let\partentry=\dosmallpartentry |
| \global\let\blankpartentry=\dosmallblankpartentry |
| @end tex |
| @summarycontents |
| |
| @tex |
| \global\let\partentry=\dopartentry |
| \global\let\blankpartentry=\doblankpartentry |
| @end tex |
| @contents |
| |
| @page |
| |
| @c --------------------------------------------------------------------- |
| @c TexInfo table of contents. |
| @c --------------------------------------------------------------------- |
| |
| @ifnottex |
| @node Top |
| @top Introduction |
| @cindex Introduction |
| |
| This manual documents the use of @command{gfortran}, |
| the GNU Fortran compiler. You can find in this manual how to invoke |
| @command{gfortran}, as well as its features and incompatibilities. |
| |
| @ifset DEVELOPMENT |
| @emph{Warning:} This document, and the compiler it describes, are still |
| under development. While efforts are made to keep it up-to-date, it might |
| not accurately reflect the status of the most recent GNU Fortran compiler. |
| @end ifset |
| |
| @comment |
| @comment When you add a new menu item, please keep the right hand |
| @comment aligned to the same column. Do not use tabs. This provides |
| @comment better formatting. |
| @comment |
| @menu |
| * Introduction:: |
| |
| Part I: Invoking GNU Fortran |
| * Invoking GNU Fortran:: Command options supported by @command{gfortran}. |
| * Runtime:: Influencing runtime behavior with environment variables. |
| |
| Part II: Language Reference |
| * Compiler Characteristics:: User-visible implementation details. |
| * Extensions:: Language extensions implemented by GNU Fortran. |
| * Mixed-Language Programming:: Interoperability with C |
| * Coarray Programming:: |
| * Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran. |
| * Intrinsic Modules:: Intrinsic modules supported by GNU Fortran. |
| |
| * Contributing:: How you can help. |
| * Copying:: GNU General Public License says |
| how you can copy and share GNU Fortran. |
| * GNU Free Documentation License:: |
| How you can copy and share this manual. |
| * Funding:: How to help assure continued work for free software. |
| * Option Index:: Index of command line options |
| * Keyword Index:: Index of concepts |
| @end menu |
| @end ifnottex |
| |
| @c --------------------------------------------------------------------- |
| @c Introduction |
| @c --------------------------------------------------------------------- |
| |
| @node Introduction |
| @chapter Introduction |
| |
| @c The following duplicates the text on the TexInfo table of contents. |
| @iftex |
| This manual documents the use of @command{gfortran}, the GNU Fortran |
| compiler. You can find in this manual how to invoke @command{gfortran}, |
| as well as its features and incompatibilities. |
| |
| @ifset DEVELOPMENT |
| @emph{Warning:} This document, and the compiler it describes, are still |
| under development. While efforts are made to keep it up-to-date, it |
| might not accurately reflect the status of the most recent GNU Fortran |
| compiler. |
| @end ifset |
| @end iftex |
| |
| @menu |
| * About GNU Fortran:: What you should know about the GNU Fortran compiler. |
| * GNU Fortran and GCC:: You can compile Fortran, C, or other programs. |
| * Standards:: Standards supported by GNU Fortran. |
| @end menu |
| |
| |
| @c --------------------------------------------------------------------- |
| @c About GNU Fortran |
| @c --------------------------------------------------------------------- |
| |
| @node About GNU Fortran |
| @section About GNU Fortran |
| |
| The GNU Fortran compiler is the successor to @command{g77}, the |
| Fortran 77 front end included in GCC prior to version 4 (released in |
| 2005). While it is backward-compatible with most @command{g77} |
| extensions and command-line options, @command{gfortran} is a completely new |
| implemention designed to support more modern dialects of Fortran. |
| GNU Fortran implements the Fortran 77, 90 and 95 standards |
| completely, most of the Fortran 2003 and 2008 standards, and some |
| features from the 2018 standard. It also implements several extensions |
| including OpenMP and OpenACC support for parallel programming. |
| |
| The GNU Fortran compiler passes the |
| @uref{http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html, |
| NIST Fortran 77 Test Suite}, and produces acceptable results on the |
| @uref{https://www.netlib.org/lapack/faq.html, LAPACK Test Suite}. |
| It also provides respectable performance on |
| the @uref{https://polyhedron.com/?page_id=175, |
| Polyhedron Fortran compiler benchmarks} and the |
| @uref{https://www.netlib.org/benchmark/livermore, |
| Livermore Fortran Kernels test}. It has been used to compile a number of |
| large real-world programs, including |
| @uref{http://hirlam.org/, the HARMONIE and HIRLAM weather forecasting code} and |
| @uref{https://github.com/dylan-jayatilaka/tonto, |
| the Tonto quantum chemistry package}; see |
| @url{https://gcc.gnu.org/@/wiki/@/GfortranApps} for an extended list. |
| |
| GNU Fortran provides the following functionality: |
| |
| @itemize @bullet |
| @item |
| Read a program, stored in a file and containing @dfn{source code} |
| instructions written in Fortran 77. |
| |
| @item |
| Translate the program into instructions a computer |
| can carry out more quickly than it takes to translate the |
| original Fortran instructions. |
| The result after compilation of a program is |
| @dfn{machine code}, |
| which is efficiently translated and processed |
| by a machine such as your computer. |
| Humans usually are not as good writing machine code |
| as they are at writing Fortran (or C++, Ada, or Java), |
| because it is easy to make tiny mistakes writing machine code. |
| |
| @item |
| Provide information about the reasons why |
| the compiler may be unable to create a binary from the source code, |
| for example if the source code is flawed. |
| The Fortran language standards require that the compiler can point out |
| mistakes in your code. |
| An incorrect usage of the language causes an @dfn{error message}. |
| |
| The compiler also attempts to diagnose cases where your |
| program contains a correct usage of the language, |
| but instructs the computer to do something questionable. |
| This kind of diagnostic message is called a @dfn{warning message}. |
| |
| @item |
| Provide optional information about the translation passes |
| from the source code to machine code. |
| This can help you to find the cause of |
| certain bugs which may not be obvious in the source code, |
| but may be more easily found at a lower level compiler output. |
| It also helps developers to find bugs in the compiler itself. |
| |
| @item |
| Provide information in the generated machine code that can |
| make it easier to find bugs in the program (using a debugging tool, |
| called a @dfn{debugger}, such as the GNU Debugger @command{gdb}). |
| |
| @item |
| Locate and gather machine code already generated to |
| perform actions requested by statements in the program. |
| This machine code is organized into @dfn{modules} and is located |
| and @dfn{linked} to the user program. |
| @end itemize |
| |
| The GNU Fortran compiler consists of several components: |
| |
| @itemize @bullet |
| @item |
| A version of the @command{gcc} command |
| (which also might be installed as the system's @command{cc} command) |
| that also understands and accepts Fortran source code. |
| The @command{gcc} command is the @dfn{driver} program for |
| all the languages in the GNU Compiler Collection (GCC); |
| With @command{gcc}, |
| you can compile the source code of any language for |
| which a front end is available in GCC. |
| |
| @item |
| The @command{gfortran} command itself, |
| which also might be installed as the |
| system's @command{f95} command. |
| @command{gfortran} is just another driver program, |
| but specifically for the Fortran compiler only. |
| The primary difference between the @command{gcc} and @command{gfortran} |
| commands is that the latter automatically links the correct libraries |
| to your program. |
| |
| @item |
| A collection of run-time libraries. |
| These libraries contain the machine code needed to support |
| capabilities of the Fortran language that are not directly |
| provided by the machine code generated by the |
| @command{gfortran} compilation phase, |
| such as intrinsic functions and subroutines, |
| and routines for interaction with files and the operating system. |
| @c and mechanisms to spawn, |
| @c unleash and pause threads in parallelized code. |
| |
| @item |
| The Fortran compiler itself, (@command{f951}). |
| This is the GNU Fortran parser and code generator, |
| linked to and interfaced with the GCC backend library. |
| @command{f951} ``translates'' the source code to |
| assembler code. You would typically not use this |
| program directly; |
| instead, the @command{gcc} or @command{gfortran} driver |
| programs call it for you. |
| @end itemize |
| |
| |
| @c --------------------------------------------------------------------- |
| @c GNU Fortran and GCC |
| @c --------------------------------------------------------------------- |
| |
| @node GNU Fortran and GCC |
| @section GNU Fortran and GCC |
| @cindex GNU Compiler Collection |
| @cindex GCC |
| |
| GNU Fortran is a part of GCC, the @dfn{GNU Compiler Collection}. GCC |
| consists of a collection of front ends for various languages, which |
| translate the source code into a language-independent form called |
| @dfn{GENERIC}. This is then processed by a common middle end which |
| provides optimization, and then passed to one of a collection of back |
| ends which generate code for different computer architectures and |
| operating systems. |
| |
| Functionally, this is implemented with a driver program (@command{gcc}) |
| which provides the command-line interface for the compiler. It calls |
| the relevant compiler front-end program (e.g., @command{f951} for |
| Fortran) for each file in the source code, and then calls the assembler |
| and linker as appropriate to produce the compiled output. In a copy of |
| GCC that has been compiled with Fortran language support enabled, |
| @command{gcc} recognizes files with @file{.f}, @file{.for}, @file{.ftn}, |
| @file{.f90}, @file{.f95}, @file{.f03} and @file{.f08} extensions as |
| Fortran source code, and compiles it accordingly. A @command{gfortran} |
| driver program is also provided, which is identical to @command{gcc} |
| except that it automatically links the Fortran runtime libraries into the |
| compiled program. |
| |
| Source files with @file{.f}, @file{.for}, @file{.fpp}, @file{.ftn}, @file{.F}, |
| @file{.FOR}, @file{.FPP}, and @file{.FTN} extensions are treated as fixed form. |
| Source files with @file{.f90}, @file{.f95}, @file{.f03}, @file{.f08}, |
| @file{.F90}, @file{.F95}, @file{.F03} and @file{.F08} extensions are |
| treated as free form. The capitalized versions of either form are run |
| through preprocessing. Source files with the lower case @file{.fpp} |
| extension are also run through preprocessing. |
| |
| This manual specifically documents the Fortran front end, which handles |
| the programming language's syntax and semantics. The aspects of GCC |
| that relate to the optimization passes and the back-end code generation |
| are documented in the GCC manual; see |
| @ref{Top,,Introduction,gcc,Using the GNU Compiler Collection (GCC)}. |
| The two manuals together provide a complete reference for the GNU |
| Fortran compiler. |
| |
| @c --------------------------------------------------------------------- |
| @c Standards |
| @c --------------------------------------------------------------------- |
| |
| @node Standards |
| @section Standards |
| @cindex Standards |
| |
| @menu |
| * Fortran 95 status:: |
| * Fortran 2003 status:: |
| * Fortran 2008 status:: |
| * Fortran 2018 status:: |
| @end menu |
| |
| Fortran is developed by the Working Group 5 of Sub-Committee 22 of the |
| Joint Technical Committee 1 of the International Organization for |
| Standardization and the International Electrotechnical Commission (IEC). |
| This group is known as @uref{http://www.nag.co.uk/sc22wg5/, WG5}. |
| Official Fortran standard documents are available for purchase |
| from ISO; a collection of free documents (typically final drafts) are |
| also available on the @uref{https://gcc.gnu.org/wiki/GFortranStandards, wiki}. |
| |
| The GNU Fortran compiler implements ISO/IEC 1539:1997 (Fortran 95). |
| As such, it can also compile essentially all standard-compliant |
| Fortran 90 and Fortran 77 programs. It also supports the ISO/IEC |
| TR-15581 enhancements to allocatable arrays. |
| |
| GNU Fortran also supports almost all of ISO/IEC 1539-1:2004 |
| (Fortran 2003) and ISO/IEC 1539-1:2010 (Fortran 2008). |
| It has partial support for features introduced in ISO/IEC |
| 1539:2018 (Fortran 2018), the most recent version of the Fortran |
| language standard, including full support for the Technical Specification |
| @code{Further Interoperability of Fortran with C} (ISO/IEC TS 29113:2012). |
| More details on support for these standards can be |
| found in the following sections of the documentation. |
| |
| Additionally, the GNU Fortran compilers supports the OpenMP specification |
| (version 4.5 and partial support of the features of the 5.0 version, |
| @url{https://openmp.org/@/specifications/}). |
| There also is support for the OpenACC specification (targeting |
| version 2.6, @uref{https://www.openacc.org/}). See |
| @uref{https://gcc.gnu.org/wiki/OpenACC} for more information. |
| |
| @node Fortran 95 status |
| @subsection Fortran 95 status |
| @cindex Varying length strings |
| @cindex strings, varying length |
| @cindex conditional compilation |
| |
| The Fortran 95 standard specifies in Part 2 (ISO/IEC 1539-2:2000) |
| varying length character strings. While GNU Fortran currently does not |
| support such strings directly, there exist two Fortran implementations |
| for them, which work with GNU Fortran. One can be found at |
| @uref{http://user.astro.wisc.edu/~townsend/static.php?ref=iso-varying-string}. |
| |
| Deferred-length character strings of Fortran 2003 supports part of |
| the features of @code{ISO_VARYING_STRING} and should be considered as |
| replacement. (Namely, allocatable or pointers of the type |
| @code{character(len=:)}.) |
| |
| Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines |
| Conditional Compilation, which is not widely used and not directly |
| supported by the GNU Fortran compiler. You can use the program coco |
| to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}). |
| |
| @node Fortran 2003 status |
| @subsection Fortran 2003 status |
| |
| GNU Fortran implements the Fortran 2003 (ISO/IEC 1539-1:2004) standard |
| except for finalization support, which is incomplete. |
| See the |
| @uref{https://gcc.gnu.org/wiki/Fortran2003, wiki page} for a full list |
| of new features introduced by Fortran 2003 and their implementation status. |
| |
| @node Fortran 2008 status |
| @subsection Fortran 2008 status |
| |
| The GNU Fortran compiler supports almost all features of Fortran 2008; |
| the @uref{https://gcc.gnu.org/wiki/Fortran2008Status, wiki} |
| has some information about the current implementation status. |
| In particular, the following are not yet supported: |
| |
| @itemize @bullet |
| @item |
| @code{DO CONCURRENT} and @code{FORALL} do not recognize a |
| type-spec in the loop header. |
| |
| @item |
| The change to permit any constant expression in subscripts and |
| nested implied-do limits in a @code{DATA} statement has not been implemented. |
| @end itemize |
| |
| |
| @node Fortran 2018 status |
| @subsection Fortran 2018 status |
| |
| Fortran 2018 (ISO/IEC 1539:2018) is the most recent version |
| of the Fortran language standard. GNU Fortran implements some of the |
| new features of this standard: |
| |
| @itemize @bullet |
| @item |
| All Fortran 2018 features derived from ISO/IEC TS 29113:2012, |
| ``Further Interoperability of Fortran with C'', are supported by GNU Fortran. |
| This includes assumed-type and assumed-rank objects and |
| the @code{SELECT RANK} construct as well as the parts relating to |
| @code{BIND(C)} functions. |
| See also @ref{Further Interoperability of Fortran with C}. |
| |
| @item |
| GNU Fortran supports a subset of features derived from ISO/IEC TS 18508:2015, |
| ``Additional Parallel Features in Fortran'': |
| |
| @itemize @bullet |
| @item |
| The new atomic ADD, CAS, FETCH and ADD/OR/XOR, OR and XOR intrinsics. |
| |
| @item |
| The @code{CO_MIN} and @code{CO_MAX} and @code{SUM} reduction intrinsics, |
| and the @code{CO_BROADCAST} and @code{CO_REDUCE} intrinsic, except that those |
| do not support polymorphic types or types with allocatable, pointer or |
| polymorphic components. |
| |
| @item |
| Events (@code{EVENT POST}, @code{EVENT WAIT}, @code{EVENT_QUERY}). |
| |
| @item |
| Failed images (@code{FAIL IMAGE}, @code{IMAGE_STATUS}, |
| @code{FAILED_IMAGES}, @code{STOPPED_IMAGES}). |
| |
| @end itemize |
| |
| @item |
| An @code{ERROR STOP} statement is permitted in a @code{PURE} |
| procedure. |
| |
| @item |
| GNU Fortran supports the @code{IMPLICIT NONE} statement with an |
| @code{implicit-none-spec-list}. |
| |
| @item |
| The behavior of the @code{INQUIRE} statement with the @code{RECL=} |
| specifier now conforms to Fortran 2018. |
| |
| @end itemize |
| |
| |
| @c ===================================================================== |
| @c PART I: INVOCATION REFERENCE |
| @c ===================================================================== |
| |
| @tex |
| \part{I}{Invoking GNU Fortran} |
| @end tex |
| |
| @c --------------------------------------------------------------------- |
| @c Compiler Options |
| @c --------------------------------------------------------------------- |
| |
| @include invoke.texi |
| |
| |
| @c --------------------------------------------------------------------- |
| @c Runtime |
| @c --------------------------------------------------------------------- |
| |
| @node Runtime |
| @chapter Runtime: Influencing runtime behavior with environment variables |
| @cindex environment variable |
| |
| The behavior of the @command{gfortran} can be influenced by |
| environment variables. |
| |
| Malformed environment variables are silently ignored. |
| |
| @menu |
| * TMPDIR:: Directory for scratch files |
| * GFORTRAN_STDIN_UNIT:: Unit number for standard input |
| * GFORTRAN_STDOUT_UNIT:: Unit number for standard output |
| * GFORTRAN_STDERR_UNIT:: Unit number for standard error |
| * GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units |
| * GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units. |
| * GFORTRAN_SHOW_LOCUS:: Show location for runtime errors |
| * GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted |
| * GFORTRAN_LIST_SEPARATOR:: Separator for list output |
| * GFORTRAN_CONVERT_UNIT:: Set conversion for unformatted I/O |
| * GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors |
| * GFORTRAN_FORMATTED_BUFFER_SIZE:: Buffer size for formatted files |
| * GFORTRAN_UNFORMATTED_BUFFER_SIZE:: Buffer size for unformatted files |
| @end menu |
| |
| @node TMPDIR |
| @section @env{TMPDIR}---Directory for scratch files |
| |
| When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to |
| create the file in one of the potential directories by testing each |
| directory in the order below. |
| |
| @enumerate |
| @item |
| The environment variable @env{TMPDIR}, if it exists. |
| |
| @item |
| On the MinGW target, the directory returned by the @code{GetTempPath} |
| function. Alternatively, on the Cygwin target, the @env{TMP} and |
| @env{TEMP} environment variables, if they exist, in that order. |
| |
| @item |
| The @code{P_tmpdir} macro if it is defined, otherwise the directory |
| @file{/tmp}. |
| @end enumerate |
| |
| @node GFORTRAN_STDIN_UNIT |
| @section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input |
| |
| This environment variable can be used to select the unit number |
| preconnected to standard input. This must be a positive integer. |
| The default value is 5. |
| |
| @node GFORTRAN_STDOUT_UNIT |
| @section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output |
| |
| This environment variable can be used to select the unit number |
| preconnected to standard output. This must be a positive integer. |
| The default value is 6. |
| |
| @node GFORTRAN_STDERR_UNIT |
| @section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error |
| |
| This environment variable can be used to select the unit number |
| preconnected to standard error. This must be a positive integer. |
| The default value is 0. |
| |
| @node GFORTRAN_UNBUFFERED_ALL |
| @section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units |
| |
| This environment variable controls whether all I/O is unbuffered. If |
| the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is |
| unbuffered. This will slow down small sequential reads and writes. If |
| the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. |
| This is the default. |
| |
| @node GFORTRAN_UNBUFFERED_PRECONNECTED |
| @section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units |
| |
| The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls |
| whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) is unbuffered. If |
| the first letter is @samp{y}, @samp{Y} or @samp{1}, I/O is unbuffered. This |
| will slow down small sequential reads and writes. If the first letter |
| is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. This is the default. |
| |
| @node GFORTRAN_SHOW_LOCUS |
| @section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors |
| |
| If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and |
| line numbers for runtime errors are printed. If the first letter is |
| @samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers |
| for runtime errors. The default is to print the location. |
| |
| @node GFORTRAN_OPTIONAL_PLUS |
| @section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted |
| |
| If the first letter is @samp{y}, @samp{Y} or @samp{1}, |
| a plus sign is printed |
| where permitted by the Fortran standard. If the first letter |
| is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed |
| in most cases. Default is not to print plus signs. |
| |
| @node GFORTRAN_LIST_SEPARATOR |
| @section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output |
| |
| This environment variable specifies the separator when writing |
| list-directed output. It may contain any number of spaces and |
| at most one comma. If you specify this on the command line, |
| be sure to quote spaces, as in |
| @smallexample |
| $ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out |
| @end smallexample |
| when @command{a.out} is the compiled Fortran program that you want to run. |
| Default is a single space. |
| |
| @node GFORTRAN_CONVERT_UNIT |
| @section @env{GFORTRAN_CONVERT_UNIT}---Set conversion for unformatted I/O |
| |
| By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible |
| to change the representation of data for unformatted files. |
| The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable for |
| most systems is: |
| @smallexample |
| GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ; |
| mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ; |
| exception: mode ':' unit_list | unit_list ; |
| unit_list: unit_spec | unit_list unit_spec ; |
| unit_spec: INTEGER | INTEGER '-' INTEGER ; |
| @end smallexample |
| The variable consists of an optional default mode, followed by |
| a list of optional exceptions, which are separated by semicolons |
| from the preceding default and each other. Each exception consists |
| of a format and a comma-separated list of units. Valid values for |
| the modes are the same as for the @code{CONVERT} specifier: |
| |
| @itemize @w{} |
| @item @code{NATIVE} Use the native format. This is the default. |
| @item @code{SWAP} Swap between little- and big-endian. |
| @item @code{LITTLE_ENDIAN} Use the little-endian format |
| for unformatted files. |
| @item @code{BIG_ENDIAN} Use the big-endian format for unformatted files. |
| @end itemize |
| For POWER systems which support @option{-mabi=ieeelongdouble}, |
| there are additional options, which can be combined with the |
| others with commas. Those are |
| @itemize @w{} |
| @item @code{R16_IEEE} Use IEEE 128-bit format for @code{REAL(KIND=16)}. |
| @item @code{R16_IBM} Use IBM @code{long double} format for |
| @code{REAL(KIND=16)}. |
| @end itemize |
| A missing mode for an exception is taken to mean @code{BIG_ENDIAN}. |
| Examples of values for @env{GFORTRAN_CONVERT_UNIT} are: |
| @itemize @w{} |
| @item @code{'big_endian'} Do all unformatted I/O in big_endian mode. |
| @item @code{'little_endian;native:10-20,25'} Do all unformatted I/O |
| in little_endian mode, except for units 10 to 20 and 25, which are in |
| native format. |
| @item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native. |
| @item @code{'big_endian,r16_ibm'} Do all unformatted I/O in big-endian |
| mode and use IBM long double for output of @code{REAL(KIND=16)} values. |
| @end itemize |
| |
| Setting the environment variables should be done on the command |
| line or via the @command{export} |
| command for @command{sh}-compatible shells and via @command{setenv} |
| for @command{csh}-compatible shells. |
| |
| Example for @command{sh}: |
| @smallexample |
| $ gfortran foo.f90 |
| $ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out |
| @end smallexample |
| |
| Example code for @command{csh}: |
| @smallexample |
| % gfortran foo.f90 |
| % setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20' |
| % ./a.out |
| @end smallexample |
| |
| Using anything but the native representation for unformatted data |
| carries a significant speed overhead. If speed in this area matters |
| to you, it is best if you use this only for data that needs to be |
| portable. |
| |
| @xref{CONVERT specifier}, for an alternative way to specify the |
| data representation for unformatted files. @xref{Runtime Options}, for |
| setting a default data representation for the whole program. The |
| @code{CONVERT} specifier overrides the @option{-fconvert} compile options. |
| |
| @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT |
| environment variable will override the CONVERT specifier in the |
| open statement}. This is to give control over data formats to |
| users who do not have the source code of their program available. |
| |
| @node GFORTRAN_ERROR_BACKTRACE |
| @section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors |
| |
| If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to @samp{y}, |
| @samp{Y} or @samp{1} (only the first letter is relevant) then a |
| backtrace is printed when a serious run-time error occurs. To disable |
| the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}. |
| Default is to print a backtrace unless the @option{-fno-backtrace} |
| compile option was used. |
| |
| @node GFORTRAN_FORMATTED_BUFFER_SIZE |
| @section @env{GFORTRAN_FORMATTED_BUFFER_SIZE}---Set buffer size for formatted I/O |
| |
| The @env{GFORTRAN_FORMATTED_BUFFER_SIZE} environment variable |
| specifies buffer size in bytes to be used for formatted output. |
| The default value is 8192. |
| |
| @node GFORTRAN_UNFORMATTED_BUFFER_SIZE |
| @section @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE}---Set buffer size for unformatted I/O |
| |
| The @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE} environment variable |
| specifies buffer size in bytes to be used for unformatted output. |
| The default value is 131072. |
| |
| @c ===================================================================== |
| @c PART II: LANGUAGE REFERENCE |
| @c ===================================================================== |
| |
| @tex |
| \part{II}{Language Reference} |
| @end tex |
| |
| |
| |
| @c --------------------------------------------------------------------- |
| @c Compiler Characteristics |
| @c --------------------------------------------------------------------- |
| |
| @node Compiler Characteristics |
| @chapter Compiler Characteristics |
| |
| This chapter describes certain characteristics of the GNU Fortran |
| compiler, that are not specified by the Fortran standard, but which |
| might in some way or another become visible to the programmer. |
| |
| @menu |
| * KIND Type Parameters:: |
| * Internal representation of LOGICAL variables:: |
| * Evaluation of logical expressions:: |
| * MAX and MIN intrinsics with REAL NaN arguments:: |
| * Thread-safety of the runtime library:: |
| * Data consistency and durability:: |
| * Files opened without an explicit ACTION= specifier:: |
| * File operations on symbolic links:: |
| * File format of unformatted sequential files:: |
| * Asynchronous I/O:: |
| @end menu |
| |
| |
| @node KIND Type Parameters |
| @section KIND Type Parameters |
| @cindex kind |
| |
| The @code{KIND} type parameters supported by GNU Fortran for the primitive |
| data types are: |
| |
| @table @code |
| |
| @item INTEGER |
| 1, 2, 4, 8*, 16*, default: 4** |
| |
| @item LOGICAL |
| 1, 2, 4, 8*, 16*, default: 4** |
| |
| @item REAL |
| 4, 8, 10*, 16*, default: 4*** |
| |
| @item COMPLEX |
| 4, 8, 10*, 16*, default: 4*** |
| |
| @item DOUBLE PRECISION |
| 4, 8, 10*, 16*, default: 8*** |
| |
| @item CHARACTER |
| 1, 4, default: 1 |
| |
| @end table |
| |
| @noindent |
| * not available on all systems @* |
| ** unless @option{-fdefault-integer-8} is used @* |
| *** unless @option{-fdefault-real-8} is used (see @ref{Fortran Dialect Options}) |
| |
| @noindent |
| The @code{KIND} value matches the storage size in bytes, except for |
| @code{COMPLEX} where the storage size is twice as much (or both real and |
| imaginary part are a real value of the given size). It is recommended to use |
| the @ref{SELECTED_CHAR_KIND}, @ref{SELECTED_INT_KIND} and |
| @ref{SELECTED_REAL_KIND} intrinsics or the @code{INT8}, @code{INT16}, |
| @code{INT32}, @code{INT64}, @code{REAL32}, @code{REAL64}, and @code{REAL128} |
| parameters of the @code{ISO_FORTRAN_ENV} module instead of the concrete values. |
| The available kind parameters can be found in the constant arrays |
| @code{CHARACTER_KINDS}, @code{INTEGER_KINDS}, @code{LOGICAL_KINDS} and |
| @code{REAL_KINDS} in the @ref{ISO_FORTRAN_ENV} module. For C interoperability, |
| the kind parameters of the @ref{ISO_C_BINDING} module should be used. |
| |
| |
| @node Internal representation of LOGICAL variables |
| @section Internal representation of LOGICAL variables |
| @cindex logical, variable representation |
| |
| The Fortran standard does not specify how variables of @code{LOGICAL} |
| type are represented, beyond requiring that @code{LOGICAL} variables |
| of default kind have the same storage size as default @code{INTEGER} |
| and @code{REAL} variables. The GNU Fortran internal representation is |
| as follows. |
| |
| A @code{LOGICAL(KIND=N)} variable is represented as an |
| @code{INTEGER(KIND=N)} variable, however, with only two permissible |
| values: @code{1} for @code{.TRUE.} and @code{0} for |
| @code{.FALSE.}. Any other integer value results in undefined behavior. |
| |
| See also @ref{Argument passing conventions} and @ref{Interoperability with C}. |
| |
| |
| @node Evaluation of logical expressions |
| @section Evaluation of logical expressions |
| |
| The Fortran standard does not require the compiler to evaluate all parts of an |
| expression, if they do not contribute to the final result. For logical |
| expressions with @code{.AND.} or @code{.OR.} operators, in particular, GNU |
| Fortran will optimize out function calls (even to impure functions) if the |
| result of the expression can be established without them. However, since not |
| all compilers do that, and such an optimization can potentially modify the |
| program flow and subsequent results, GNU Fortran throws warnings for such |
| situations with the @option{-Wfunction-elimination} flag. |
| |
| |
| @node MAX and MIN intrinsics with REAL NaN arguments |
| @section MAX and MIN intrinsics with REAL NaN arguments |
| @cindex MAX, MIN, NaN |
| |
| The Fortran standard does not specify what the result of the |
| @code{MAX} and @code{MIN} intrinsics are if one of the arguments is a |
| @code{NaN}. Accordingly, the GNU Fortran compiler does not specify |
| that either, as this allows for faster and more compact code to be |
| generated. If the programmer wishes to take some specific action in |
| case one of the arguments is a @code{NaN}, it is necessary to |
| explicitly test the arguments before calling @code{MAX} or @code{MIN}, |
| e.g. with the @code{IEEE_IS_NAN} function from the intrinsic module |
| @code{IEEE_ARITHMETIC}. |
| |
| |
| @node Thread-safety of the runtime library |
| @section Thread-safety of the runtime library |
| @cindex thread-safety, threads |
| |
| GNU Fortran can be used in programs with multiple threads, e.g.@: by |
| using OpenMP, by calling OS thread handling functions via the |
| @code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code |
| being called from a multi-threaded program. |
| |
| The GNU Fortran runtime library, (@code{libgfortran}), supports being |
| called concurrently from multiple threads with the following |
| exceptions. |
| |
| During library initialization, the C @code{getenv} function is used, |
| which need not be thread-safe. Similarly, the @code{getenv} |
| function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and |
| @code{GETENV} intrinsics. It is the responsibility of the user to |
| ensure that the environment is not being updated concurrently when any |
| of these actions are taking place. |
| |
| The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are |
| implemented with the @code{system} function, which need not be |
| thread-safe. It is the responsibility of the user to ensure that |
| @code{system} is not called concurrently. |
| |
| For platforms not supporting thread-safe POSIX functions, further |
| functionality might not be thread-safe. For details, please consult |
| the documentation for your operating system. |
| |
| The GNU Fortran runtime library uses various C library functions that |
| depend on the locale, such as @code{strtod} and @code{snprintf}. In |
| order to work correctly in locale-aware programs that set the locale |
| using @code{setlocale}, the locale is reset to the default ``C'' |
| locale while executing a formatted @code{READ} or @code{WRITE} |
| statement. On targets supporting the POSIX 2008 per-thread locale |
| functions (e.g. @code{newlocale}, @code{uselocale}, |
| @code{freelocale}), these are used and thus the global locale set |
| using @code{setlocale} or the per-thread locales in other threads are |
| not affected. However, on targets lacking this functionality, the |
| global LC_NUMERIC locale is set to ``C'' during the formatted I/O. |
| Thus, on such targets it's not safe to call @code{setlocale} |
| concurrently from another thread while a Fortran formatted I/O |
| operation is in progress. Also, other threads doing something |
| dependent on the LC_NUMERIC locale might not work correctly if a |
| formatted I/O operation is in progress in another thread. |
| |
| @node Data consistency and durability |
| @section Data consistency and durability |
| @cindex consistency, durability |
| |
| This section contains a brief overview of data and metadata |
| consistency and durability issues when doing I/O. |
| |
| With respect to durability, GNU Fortran makes no effort to ensure that |
| data is committed to stable storage. If this is required, the GNU |
| Fortran programmer can use the intrinsic @code{FNUM} to retrieve the |
| low level file descriptor corresponding to an open Fortran unit. Then, |
| using e.g. the @code{ISO_C_BINDING} feature, one can call the |
| underlying system call to flush dirty data to stable storage, such as |
| @code{fsync} on POSIX, @code{_commit} on MingW, or @code{fcntl(fd, |
| F_FULLSYNC, 0)} on Mac OS X. The following example shows how to call |
| fsync: |
| |
| @smallexample |
| ! Declare the interface for POSIX fsync function |
| interface |
| function fsync (fd) bind(c,name="fsync") |
| use iso_c_binding, only: c_int |
| integer(c_int), value :: fd |
| integer(c_int) :: fsync |
| end function fsync |
| end interface |
| |
| ! Variable declaration |
| integer :: ret |
| |
| ! Opening unit 10 |
| open (10,file="foo") |
| |
| ! ... |
| ! Perform I/O on unit 10 |
| ! ... |
| |
| ! Flush and sync |
| flush(10) |
| ret = fsync(fnum(10)) |
| |
| ! Handle possible error |
| if (ret /= 0) stop "Error calling FSYNC" |
| @end smallexample |
| |
| With respect to consistency, for regular files GNU Fortran uses |
| buffered I/O in order to improve performance. This buffer is flushed |
| automatically when full and in some other situations, e.g. when |
| closing a unit. It can also be explicitly flushed with the |
| @code{FLUSH} statement. Also, the buffering can be turned off with the |
| @code{GFORTRAN_UNBUFFERED_ALL} and |
| @code{GFORTRAN_UNBUFFERED_PRECONNECTED} environment variables. Special |
| files, such as terminals and pipes, are always unbuffered. Sometimes, |
| however, further things may need to be done in order to allow other |
| processes to see data that GNU Fortran has written, as follows. |
| |
| The Windows platform supports a relaxed metadata consistency model, |
| where file metadata is written to the directory lazily. This means |
| that, for instance, the @code{dir} command can show a stale size for a |
| file. One can force a directory metadata update by closing the unit, |
| or by calling @code{_commit} on the file descriptor. Note, though, |
| that @code{_commit} will force all dirty data to stable storage, which |
| is often a very slow operation. |
| |
| The Network File System (NFS) implements a relaxed consistency model |
| called open-to-close consistency. Closing a file forces dirty data and |
| metadata to be flushed to the server, and opening a file forces the |
| client to contact the server in order to revalidate cached |
| data. @code{fsync} will also force a flush of dirty data and metadata |
| to the server. Similar to @code{open} and @code{close}, acquiring and |
| releasing @code{fcntl} file locks, if the server supports them, will |
| also force cache validation and flushing dirty data and metadata. |
| |
| |
| @node Files opened without an explicit ACTION= specifier |
| @section Files opened without an explicit ACTION= specifier |
| @cindex open, action |
| |
| The Fortran standard says that if an @code{OPEN} statement is executed |
| without an explicit @code{ACTION=} specifier, the default value is |
| processor dependent. GNU Fortran behaves as follows: |
| |
| @enumerate |
| @item Attempt to open the file with @code{ACTION='READWRITE'} |
| @item If that fails, try to open with @code{ACTION='READ'} |
| @item If that fails, try to open with @code{ACTION='WRITE'} |
| @item If that fails, generate an error |
| @end enumerate |
| |
| |
| @node File operations on symbolic links |
| @section File operations on symbolic links |
| @cindex file, symbolic link |
| |
| This section documents the behavior of GNU Fortran for file operations on |
| symbolic links, on systems that support them. |
| |
| @itemize |
| |
| @item Results of INQUIRE statements of the ``inquire by file'' form will |
| relate to the target of the symbolic link. For example, |
| @code{INQUIRE(FILE="foo",EXIST=ex)} will set @var{ex} to @var{.true.} if |
| @var{foo} is a symbolic link pointing to an existing file, and @var{.false.} |
| if @var{foo} points to an non-existing file (``dangling'' symbolic link). |
| |
| @item Using the @code{OPEN} statement with a @code{STATUS="NEW"} specifier |
| on a symbolic link will result in an error condition, whether the symbolic |
| link points to an existing target or is dangling. |
| |
| @item If a symbolic link was connected, using the @code{CLOSE} statement |
| with a @code{STATUS="DELETE"} specifier will cause the symbolic link itself |
| to be deleted, not its target. |
| |
| @end itemize |
| |
| @node File format of unformatted sequential files |
| @section File format of unformatted sequential files |
| @cindex file, unformatted sequential |
| @cindex unformatted sequential |
| @cindex sequential, unformatted |
| @cindex record marker |
| @cindex subrecord |
| |
| Unformatted sequential files are stored as logical records using |
| record markers. Each logical record consists of one of more |
| subrecords. |
| |
| Each subrecord consists of a leading record marker, the data written |
| by the user program, and a trailing record marker. The record markers |
| are four-byte integers by default, and eight-byte integers if the |
| @option{-fmax-subrecord-length=8} option (which exists for backwards |
| compability only) is in effect. |
| |
| The representation of the record markers is that of unformatted files |
| given with the @option{-fconvert} option, the @ref{CONVERT specifier} |
| in an open statement or the @ref{GFORTRAN_CONVERT_UNIT} environment |
| variable. |
| |
| The maximum number of bytes of user data in a subrecord is 2147483639 |
| (2 GiB - 9) for a four-byte record marker. This limit can be lowered |
| with the @option{-fmax-subrecord-length} option, although this is |
| rarely useful. If the length of a logical record exceeds this limit, |
| the data is distributed among several subrecords. |
| |
| The absolute of the number stored in the record markers is the number |
| of bytes of user data in the corresponding subrecord. If the leading |
| record marker of a subrecord contains a negative number, another |
| subrecord follows the current one. If the trailing record marker |
| contains a negative number, then there is a preceding subrecord. |
| |
| In the most simple case, with only one subrecord per logical record, |
| both record markers contain the number of bytes of user data in the |
| record. |
| |
| The format for unformatted sequential data can be duplicated using |
| unformatted stream, as shown in the example program for an unformatted |
| record containing a single subrecord: |
| |
| @smallexample |
| program main |
| use iso_fortran_env, only: int32 |
| implicit none |
| integer(int32) :: i |
| real, dimension(10) :: a, b |
| call random_number(a) |
| open (10,file='test.dat',form='unformatted',access='stream') |
| inquire (iolength=i) a |
| write (10) i, a, i |
| close (10) |
| open (10,file='test.dat',form='unformatted') |
| read (10) b |
| if (all (a == b)) print *,'success!' |
| end program main |
| @end smallexample |
| |
| @node Asynchronous I/O |
| @section Asynchronous I/O |
| @cindex input/output, asynchronous |
| @cindex asynchronous I/O |
| |
| Asynchronous I/O is supported if the program is linked against the |
| POSIX thread library. If that is not the case, all I/O is performed |
| as synchronous. On systems which do not support pthread condition |
| variables, such as AIX, I/O is also performed as synchronous. |
| |
| On some systems, such as Darwin or Solaris, the POSIX thread library |
| is always linked in, so asynchronous I/O is always performed. On other |
| sytems, such as Linux, it is necessary to specify @option{-pthread}, |
| @option{-lpthread} or @option{-fopenmp} during the linking step. |
| |
| @c --------------------------------------------------------------------- |
| @c Extensions |
| @c --------------------------------------------------------------------- |
| |
| @c Maybe this chapter should be merged with the 'Standards' section, |
| @c whenever that is written :-) |
| |
| @node Extensions |
| @chapter Extensions |
| @cindex extensions |
| |
| The two sections below detail the extensions to standard Fortran that are |
| implemented in GNU Fortran, as well as some of the popular or |
| historically important extensions that are not (or not yet) implemented. |
| For the latter case, we explain the alternatives available to GNU Fortran |
| users, including replacement by standard-conforming code or GNU |
| extensions. |
| |
| @menu |
| * Extensions implemented in GNU Fortran:: |
| * Extensions not implemented in GNU Fortran:: |
| @end menu |
| |
| |
| @node Extensions implemented in GNU Fortran |
| @section Extensions implemented in GNU Fortran |
| @cindex extensions, implemented |
| |
| GNU Fortran implements a number of extensions over standard Fortran. |
| This chapter contains information on their syntax and meaning. There |
| are currently two categories of GNU Fortran extensions, those that |
| provide functionality beyond that provided by any standard, and those |
| that are supported by GNU Fortran purely for backward compatibility |
| with legacy compilers. By default, @option{-std=gnu} allows the |
| compiler to accept both types of extensions, but to warn about the use |
| of the latter. Specifying either @option{-std=f95}, |
| @option{-std=f2003}, @option{-std=f2008}, or @option{-std=f2018} |
| disables both types of extensions, and @option{-std=legacy} allows |
| both without warning. The special compile flag @option{-fdec} enables |
| additional compatibility extensions along with those enabled by |
| @option{-std=legacy}. |
| |
| @menu |
| * Old-style kind specifications:: |
| * Old-style variable initialization:: |
| * Extensions to namelist:: |
| * X format descriptor without count field:: |
| * Commas in FORMAT specifications:: |
| * Missing period in FORMAT specifications:: |
| * Default widths for F@comma{} G and I format descriptors:: |
| * I/O item lists:: |
| * @code{Q} exponent-letter:: |
| * BOZ literal constants:: |
| * Real array indices:: |
| * Unary operators:: |
| * Implicitly convert LOGICAL and INTEGER values:: |
| * Hollerith constants support:: |
| * Character conversion:: |
| * Cray pointers:: |
| * CONVERT specifier:: |
| * OpenMP:: |
| * OpenACC:: |
| * Argument list functions:: |
| * Read/Write after EOF marker:: |
| * STRUCTURE and RECORD:: |
| * UNION and MAP:: |
| * Type variants for integer intrinsics:: |
| * AUTOMATIC and STATIC attributes:: |
| * Extended math intrinsics:: |
| * Form feed as whitespace:: |
| * TYPE as an alias for PRINT:: |
| * %LOC as an rvalue:: |
| * .XOR. operator:: |
| * Bitwise logical operators:: |
| * Extended I/O specifiers:: |
| * Legacy PARAMETER statements:: |
| * Default exponents:: |
| @end menu |
| |
| @node Old-style kind specifications |
| @subsection Old-style kind specifications |
| @cindex kind, old-style |
| |
| GNU Fortran allows old-style kind specifications in declarations. These |
| look like: |
| @smallexample |
| TYPESPEC*size x,y,z |
| @end smallexample |
| @noindent |
| where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL}, |
| etc.), and where @code{size} is a byte count corresponding to the |
| storage size of a valid kind for that type. (For @code{COMPLEX} |
| variables, @code{size} is the total size of the real and imaginary |
| parts.) The statement then declares @code{x}, @code{y} and @code{z} to |
| be of type @code{TYPESPEC} with the appropriate kind. This is |
| equivalent to the standard-conforming declaration |
| @smallexample |
| TYPESPEC(k) x,y,z |
| @end smallexample |
| @noindent |
| where @code{k} is the kind parameter suitable for the intended precision. As |
| kind parameters are implementation-dependent, use the @code{KIND}, |
| @code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve |
| the correct value, for instance @code{REAL*8 x} can be replaced by: |
| @smallexample |
| INTEGER, PARAMETER :: dbl = KIND(1.0d0) |
| REAL(KIND=dbl) :: x |
| @end smallexample |
| |
| @node Old-style variable initialization |
| @subsection Old-style variable initialization |
| |
| GNU Fortran allows old-style initialization of variables of the |
| form: |
| @smallexample |
| INTEGER i/1/,j/2/ |
| REAL x(2,2) /3*0.,1./ |
| @end smallexample |
| The syntax for the initializers is as for the @code{DATA} statement, but |
| unlike in a @code{DATA} statement, an initializer only applies to the |
| variable immediately preceding the initialization. In other words, |
| something like @code{INTEGER I,J/2,3/} is not valid. This style of |
| initialization is only allowed in declarations without double colons |
| (@code{::}); the double colons were introduced in Fortran 90, which also |
| introduced a standard syntax for initializing variables in type |
| declarations. |
| |
| Examples of standard-conforming code equivalent to the above example |
| are: |
| @smallexample |
| ! Fortran 90 |
| INTEGER :: i = 1, j = 2 |
| REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x)) |
| ! Fortran 77 |
| INTEGER i, j |
| REAL x(2,2) |
| DATA i/1/, j/2/, x/3*0.,1./ |
| @end smallexample |
| |
| Note that variables which are explicitly initialized in declarations |
| or in @code{DATA} statements automatically acquire the @code{SAVE} |
| attribute. |
| |
| @node Extensions to namelist |
| @subsection Extensions to namelist |
| @cindex Namelist |
| |
| GNU Fortran fully supports the Fortran 95 standard for namelist I/O |
| including array qualifiers, substrings and fully qualified derived types. |
| The output from a namelist write is compatible with namelist read. The |
| output has all names in upper case and indentation to column 1 after the |
| namelist name. Two extensions are permitted: |
| |
| Old-style use of @samp{$} instead of @samp{&} |
| @smallexample |
| $MYNML |
| X(:)%Y(2) = 1.0 2.0 3.0 |
| CH(1:4) = "abcd" |
| $END |
| @end smallexample |
| |
| It should be noted that the default terminator is @samp{/} rather than |
| @samp{&END}. |
| |
| Querying of the namelist when inputting from stdin. After at least |
| one space, entering @samp{?} sends to stdout the namelist name and the names of |
| the variables in the namelist: |
| @smallexample |
| ? |
| |
| &mynml |
| x |
| x%y |
| ch |
| &end |
| @end smallexample |
| |
| Entering @samp{=?} outputs the namelist to stdout, as if |
| @code{WRITE(*,NML = mynml)} had been called: |
| @smallexample |
| =? |
| |
| &MYNML |
| X(1)%Y= 0.000000 , 1.000000 , 0.000000 , |
| X(2)%Y= 0.000000 , 2.000000 , 0.000000 , |
| X(3)%Y= 0.000000 , 3.000000 , 0.000000 , |
| CH=abcd, / |
| @end smallexample |
| |
| To aid this dialog, when input is from stdin, errors send their |
| messages to stderr and execution continues, even if @code{IOSTAT} is set. |
| |
| @code{PRINT} namelist is permitted. This causes an error if |
| @option{-std=f95} is used. |
| @smallexample |
| PROGRAM test_print |
| REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/) |
| NAMELIST /mynml/ x |
| PRINT mynml |
| END PROGRAM test_print |
| @end smallexample |
| |
| Expanded namelist reads are permitted. This causes an error if |
| @option{-std=f95} is used. In the following example, the first element |
| of the array will be given the value 0.00 and the two succeeding |
| elements will be given the values 1.00 and 2.00. |
| @smallexample |
| &MYNML |
| X(1,1) = 0.00 , 1.00 , 2.00 |
| / |
| @end smallexample |
| |
| When writing a namelist, if no @code{DELIM=} is specified, by default a |
| double quote is used to delimit character strings. If -std=F95, F2003, |
| or F2008, etc, the delim status is set to 'none'. Defaulting to |
| quotes ensures that namelists with character strings can be subsequently |
| read back in accurately. |
| |
| @node X format descriptor without count field |
| @subsection @code{X} format descriptor without count field |
| |
| To support legacy codes, GNU Fortran permits the count field of the |
| @code{X} edit descriptor in @code{FORMAT} statements to be omitted. |
| When omitted, the count is implicitly assumed to be one. |
| |
| @smallexample |
| PRINT 10, 2, 3 |
| 10 FORMAT (I1, X, I1) |
| @end smallexample |
| |
| @node Commas in FORMAT specifications |
| @subsection Commas in @code{FORMAT} specifications |
| |
| To support legacy codes, GNU Fortran allows the comma separator |
| to be omitted immediately before and after character string edit |
| descriptors in @code{FORMAT} statements. A comma with no following format |
| decriptor is permited if the @option{-fdec-blank-format-item} is given on |
| the command line. This is considered non-conforming code and is |
| discouraged. |
| |
| @smallexample |
| PRINT 10, 2, 3 |
| 10 FORMAT ('FOO='I1' BAR='I2) |
| print 20, 5, 6 |
| 20 FORMAT (I3, I3,) |
| @end smallexample |
| |
| |
| @node Missing period in FORMAT specifications |
| @subsection Missing period in @code{FORMAT} specifications |
| |
| To support legacy codes, GNU Fortran allows missing periods in format |
| specifications if and only if @option{-std=legacy} is given on the |
| command line. This is considered non-conforming code and is |
| discouraged. |
| |
| @smallexample |
| REAL :: value |
| READ(*,10) value |
| 10 FORMAT ('F4') |
| @end smallexample |
| |
| @node Default widths for F@comma{} G and I format descriptors |
| @subsection Default widths for @code{F}, @code{G} and @code{I} format descriptors |
| |
| To support legacy codes, GNU Fortran allows width to be omitted from format |
| specifications if and only if @option{-fdec-format-defaults} is given on the |
| command line. Default widths will be used. This is considered non-conforming |
| code and is discouraged. |
| |
| @smallexample |
| REAL :: value1 |
| INTEGER :: value2 |
| WRITE(*,10) value1, value1, value2 |
| 10 FORMAT ('F, G, I') |
| @end smallexample |
| |
| |
| @node I/O item lists |
| @subsection I/O item lists |
| @cindex I/O item lists |
| |
| To support legacy codes, GNU Fortran allows the input item list |
| of the @code{READ} statement, and the output item lists of the |
| @code{WRITE} and @code{PRINT} statements, to start with a comma. |
| |
| @node @code{Q} exponent-letter |
| @subsection @code{Q} exponent-letter |
| @cindex @code{Q} exponent-letter |
| |
| GNU Fortran accepts real literal constants with an exponent-letter |
| of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted |
| as a @code{REAL(16)} entity on targets that support this type. If |
| the target does not support @code{REAL(16)} but has a @code{REAL(10)} |
| type, then the real-literal-constant will be interpreted as a |
| @code{REAL(10)} entity. In the absence of @code{REAL(16)} and |
| @code{REAL(10)}, an error will occur. |
| |
| @node BOZ literal constants |
| @subsection BOZ literal constants |
| @cindex BOZ literal constants |
| |
| Besides decimal constants, Fortran also supports binary (@code{b}), |
| octal (@code{o}) and hexadecimal (@code{z}) integer constants. The |
| syntax is: @samp{prefix quote digits quote}, where the prefix is |
| either @code{b}, @code{o} or @code{z}, quote is either @code{'} or |
| @code{"} and the digits are @code{0} or @code{1} for binary, |
| between @code{0} and @code{7} for octal, and between @code{0} and |
| @code{F} for hexadecimal. (Example: @code{b'01011101'}.) |
| |
| Up to Fortran 95, BOZ literal constants were only allowed to initialize |
| integer variables in DATA statements. Since Fortran 2003 BOZ literal |
| constants are also allowed as actual arguments to the @code{REAL}, |
| @code{DBLE}, @code{INT} and @code{CMPLX} intrinsic functions. |
| The BOZ literal constant is simply a string of bits, which is padded |
| or truncated as needed, during conversion to a numeric type. The |
| Fortran standard states that the treatment of the sign bit is processor |
| dependent. Gfortran interprets the sign bit as a user would expect. |
| |
| As a deprecated extension, GNU Fortran allows hexadecimal BOZ literal |
| constants to be specified using the @code{X} prefix. That the BOZ literal |
| constant can also be specified by adding a suffix to the string, for |
| example, @code{Z'ABC'} and @code{'ABC'X} are equivalent. Additionally, |
| as extension, BOZ literals are permitted in some contexts outside of |
| @code{DATA} and the intrinsic functions listed in the Fortran standard. |
| Use @option{-fallow-invalid-boz} to enable the extension. |
| |
| @node Real array indices |
| @subsection Real array indices |
| @cindex array, indices of type real |
| |
| As an extension, GNU Fortran allows the use of @code{REAL} expressions |
| or variables as array indices. |
| |
| @node Unary operators |
| @subsection Unary operators |
| @cindex operators, unary |
| |
| As an extension, GNU Fortran allows unary plus and unary minus operators |
| to appear as the second operand of binary arithmetic operators without |
| the need for parenthesis. |
| |
| @smallexample |
| X = Y * -Z |
| @end smallexample |
| |
| @node Implicitly convert LOGICAL and INTEGER values |
| @subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values |
| @cindex conversion, to integer |
| @cindex conversion, to logical |
| |
| As an extension for backwards compatibility with other compilers, GNU |
| Fortran allows the implicit conversion of @code{LOGICAL} values to |
| @code{INTEGER} values and vice versa. When converting from a |
| @code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as |
| zero, and @code{.TRUE.} is interpreted as one. When converting from |
| @code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as |
| @code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}. |
| |
| @smallexample |
| LOGICAL :: l |
| l = 1 |
| @end smallexample |
| @smallexample |
| INTEGER :: i |
| i = .TRUE. |
| @end smallexample |
| |
| However, there is no implicit conversion of @code{INTEGER} values in |
| @code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values |
| in I/O operations. |
| |
| @node Hollerith constants support |
| @subsection Hollerith constants support |
| @cindex Hollerith constants |
| |
| GNU Fortran supports Hollerith constants in assignments, @code{DATA} |
| statements, function and subroutine arguments. A Hollerith constant is |
| written as a string of characters preceded by an integer constant |
| indicating the character count, and the letter @code{H} or |
| @code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER}, |
| @code{REAL}, or @code{COMPLEX}), @code{LOGICAL} or @code{CHARACTER} variable. |
| The constant will be padded with spaces or truncated to fit the size of |
| the variable in which it is stored. |
| |
| Examples of valid uses of Hollerith constants: |
| @smallexample |
| complex*16 x(2) |
| data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/ |
| x(1) = 16HABCDEFGHIJKLMNOP |
| call foo (4h abc) |
| @end smallexample |
| |
| Examples of Hollerith constants: |
| @smallexample |
| integer*4 a |
| a = 0H ! Invalid, at least one character is needed. |
| a = 4HAB12 ! Valid |
| a = 8H12345678 ! Valid, but the Hollerith constant will be truncated. |
| a = 3Hxyz ! Valid, but the Hollerith constant will be padded. |
| @end smallexample |
| |
| In general, Hollerith constants were used to provide a rudimentary |
| facility for handling character strings in early Fortran compilers, |
| prior to the introduction of @code{CHARACTER} variables in Fortran 77; |
| in those cases, the standard-compliant equivalent is to convert the |
| program to use proper character strings. On occasion, there may be a |
| case where the intent is specifically to initialize a numeric variable |
| with a given byte sequence. In these cases, the same result can be |
| obtained by using the @code{TRANSFER} statement, as in this example. |
| @smallexample |
| integer(kind=4) :: a |
| a = transfer ("abcd", a) ! equivalent to: a = 4Habcd |
| @end smallexample |
| |
| The use of the @option{-fdec} option extends support of Hollerith constants |
| to comparisons: |
| @smallexample |
| integer*4 a |
| a = 4hABCD |
| if (a .ne. 4habcd) then |
| write(*,*) "no match" |
| end if |
| @end smallexample |
| |
| Supported types are numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}), |
| and @code{CHARACTER}. |
| |
| @node Character conversion |
| @subsection Character conversion |
| @cindex conversion, to character |
| |
| Allowing character literals to be used in a similar way to Hollerith constants |
| is a non-standard extension. This feature is enabled using |
| -fdec-char-conversions and only applies to character literals of @code{kind=1}. |
| |
| Character literals can be used in @code{DATA} statements and assignments with |
| numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}) or @code{LOGICAL} |
| variables. Like Hollerith constants they are copied byte-wise fashion. The |
| constant will be padded with spaces or truncated to fit the size of the |
| variable in which it is stored. |
| |
| Examples: |
| @smallexample |
| integer*4 x |
| data x / 'abcd' / |
| |
| x = 'A' ! Will be padded. |
| x = 'ab1234' ! Will be truncated. |
| @end smallexample |
| |
| |
| @node Cray pointers |
| @subsection Cray pointers |
| @cindex pointer, Cray |
| |
| Cray pointers are part of a non-standard extension that provides a |
| C-like pointer in Fortran. This is accomplished through a pair of |
| variables: an integer "pointer" that holds a memory address, and a |
| "pointee" that is used to dereference the pointer. |
| |
| Pointer/pointee pairs are declared in statements of the form: |
| @smallexample |
| pointer ( <pointer> , <pointee> ) |
| @end smallexample |
| or, |
| @smallexample |
| pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ... |
| @end smallexample |
| The pointer is an integer that is intended to hold a memory address. |
| The pointee may be an array or scalar. |
| If an assumed-size array is permitted within the scoping unit, a |
| pointee can be an assumed-size array. |
| That is, the last dimension may be left unspecified by using a @code{*} |
| in place of a value. A pointee cannot be an assumed shape array. |
| No space is allocated for the pointee. |
| |
| The pointee may have its type declared before or after the pointer |
| statement, and its array specification (if any) may be declared |
| before, during, or after the pointer statement. The pointer may be |
| declared as an integer prior to the pointer statement. However, some |
| machines have default integer sizes that are different than the size |
| of a pointer, and so the following code is not portable: |
| @smallexample |
| integer ipt |
| pointer (ipt, iarr) |
| @end smallexample |
| If a pointer is declared with a kind that is too small, the compiler |
| will issue a warning; the resulting binary will probably not work |
| correctly, because the memory addresses stored in the pointers may be |
| truncated. It is safer to omit the first line of the above example; |
| if explicit declaration of ipt's type is omitted, then the compiler |
| will ensure that ipt is an integer variable large enough to hold a |
| pointer. |
| |
| Pointer arithmetic is valid with Cray pointers, but it is not the same |
| as C pointer arithmetic. Cray pointers are just ordinary integers, so |
| the user is responsible for determining how many bytes to add to a |
| pointer in order to increment it. Consider the following example: |
| @smallexample |
| real target(10) |
| real pointee(10) |
| pointer (ipt, pointee) |
| ipt = loc (target) |
| ipt = ipt + 1 |
| @end smallexample |
| The last statement does not set @code{ipt} to the address of |
| @code{target(1)}, as it would in C pointer arithmetic. Adding @code{1} |
| to @code{ipt} just adds one byte to the address stored in @code{ipt}. |
| |
| Any expression involving the pointee will be translated to use the |
| value stored in the pointer as the base address. |
| |
| To get the address of elements, this extension provides an intrinsic |
| function @code{LOC()}. The @code{LOC()} function is equivalent to the |
| @code{&} operator in C, except the address is cast to an integer type: |
| @smallexample |
| real ar(10) |
| pointer(ipt, arpte(10)) |
| real arpte |
| ipt = loc(ar) ! Makes arpte is an alias for ar |
| arpte(1) = 1.0 ! Sets ar(1) to 1.0 |
| @end smallexample |
| The pointer can also be set by a call to the @code{MALLOC} intrinsic |
| (see @ref{MALLOC}). |
| |
| Cray pointees often are used to alias an existing variable. For |
| example: |
| @smallexample |
| integer target(10) |
| integer iarr(10) |
| pointer (ipt, iarr) |
| ipt = loc(target) |
| @end smallexample |
| As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for |
| @code{target}. The optimizer, however, will not detect this aliasing, so |
| it is unsafe to use @code{iarr} and @code{target} simultaneously. Using |
| a pointee in any way that violates the Fortran aliasing rules or |
| assumptions is illegal. It is the user's responsibility to avoid doing |
| this; the compiler works under the assumption that no such aliasing |
| occurs. |
| |
| Cray pointers will work correctly when there is no aliasing (i.e., when |
| they are used to access a dynamically allocated block of memory), and |
| also in any routine where a pointee is used, but any variable with which |
| it shares storage is not used. Code that violates these rules may not |
| run as the user intends. This is not a bug in the optimizer; any code |
| that violates the aliasing rules is illegal. (Note that this is not |
| unique to GNU Fortran; any Fortran compiler that supports Cray pointers |
| will ``incorrectly'' optimize code with illegal aliasing.) |
| |
| There are a number of restrictions on the attributes that can be applied |
| to Cray pointers and pointees. Pointees may not have the |
| @code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY}, |
| @code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers |
| may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET}, |
| @code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor |
| may they be function results. Pointees may not occur in more than one |
| pointer statement. A pointee cannot be a pointer. Pointees cannot occur |
| in equivalence, common, or data statements. |
| |
| A Cray pointer may also point to a function or a subroutine. For |
| example, the following excerpt is valid: |
| @smallexample |
| implicit none |
| external sub |
| pointer (subptr,subpte) |
| external subpte |
| subptr = loc(sub) |
| call subpte() |
| [...] |
| subroutine sub |
| [...] |
| end subroutine sub |
| @end smallexample |
| |
| A pointer may be modified during the course of a program, and this |
| will change the location to which the pointee refers. However, when |
| pointees are passed as arguments, they are treated as ordinary |
| variables in the invoked function. Subsequent changes to the pointer |
| will not change the base address of the array that was passed. |
| |
| @node CONVERT specifier |
| @subsection @code{CONVERT} specifier |
| @cindex @code{CONVERT} specifier |
| |
| GNU Fortran allows the conversion of unformatted data between little- |
| and big-endian representation to facilitate moving of data |
| between different systems. The conversion can be indicated with |
| the @code{CONVERT} specifier on the @code{OPEN} statement. |
| @xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying |
| the data format via an environment variable. |
| |
| Valid values for @code{CONVERT} on most systems are: |
| @itemize @w{} |
| @item @code{CONVERT='NATIVE'} Use the native format. This is the default. |
| @item @code{CONVERT='SWAP'} Swap between little- and big-endian. |
| @item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation |
| for unformatted files. |
| @item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for |
| unformatted files. |
| @end itemize |
| On POWER systems which support @option{-mabi=ieeelongdouble}, |
| there are additional options, which can be combined with the others |
| with commas. Those are |
| @itemize @w{} |
| @item @code{CONVERT='R16_IEEE'} Use IEEE 128-bit format for |
| @code{REAL(KIND=16)}. |
| @item @code{CONVERT='R16_IBM'} Use IBM @code{long double} format for |
| real@code{REAL(KIND=16)}. |
| @end itemize |
| |
| Using the option could look like this: |
| @smallexample |
| open(file='big.dat',form='unformatted',access='sequential', & |
| convert='big_endian') |
| @end smallexample |
| |
| The value of the conversion can be queried by using |
| @code{INQUIRE(CONVERT=ch)}. The values returned are |
| @code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}. |
| |
| @code{CONVERT} works between big- and little-endian for |
| @code{INTEGER} values of all supported kinds and for @code{REAL} |
| on IEEE systems of kinds 4 and 8. Conversion between different |
| ``extended double'' types on different architectures such as |
| m68k and x86_64, which GNU Fortran |
| supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will |
| probably not work. |
| |
| @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT |
| environment variable will override the CONVERT specifier in the |
| open statement}. This is to give control over data formats to |
| users who do not have the source code of their program available. |
| |
| Using anything but the native representation for unformatted data |
| carries a significant speed overhead. If speed in this area matters |
| to you, it is best if you use this only for data that needs to be |
| portable. |
| |
| @node OpenMP |
| @subsection OpenMP |
| @cindex OpenMP |
| |
| OpenMP (Open Multi-Processing) is an application programming |
| interface (API) that supports multi-platform shared memory |
| multiprocessing programming in C/C++ and Fortran on many |
| architectures, including Unix and Microsoft Windows platforms. |
| It consists of a set of compiler directives, library routines, |
| and environment variables that influence run-time behavior. |
| |
| GNU Fortran strives to be compatible to the |
| @uref{https://openmp.org/specifications/, |
| OpenMP Application Program Interface v4.5}. |
| |
| To enable the processing of the OpenMP directive @code{!$omp} in |
| free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp} |
| directives in fixed form; the @code{!$} conditional compilation sentinels |
| in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels |
| in fixed form, @command{gfortran} needs to be invoked with the |
| @option{-fopenmp}. This also arranges for automatic linking of the |
| GNU Offloading and Multi Processing Runtime Library |
| @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime |
| Library}. |
| |
| The OpenMP Fortran runtime library routines are provided both in a |
| form of a Fortran 90 module named @code{omp_lib} and in a form of |
| a Fortran @code{include} file named @file{omp_lib.h}. |
| |
| An example of a parallelized loop taken from Appendix A.1 of |
| the OpenMP Application Program Interface v2.5: |
| @smallexample |
| SUBROUTINE A1(N, A, B) |
| INTEGER I, N |
| REAL B(N), A(N) |
| !$OMP PARALLEL DO !I is private by default |
| DO I=2,N |
| B(I) = (A(I) + A(I-1)) / 2.0 |
| ENDDO |
| !$OMP END PARALLEL DO |
| END SUBROUTINE A1 |
| @end smallexample |
| |
| Please note: |
| @itemize |
| @item |
| @option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays |
| will be allocated on the stack. When porting existing code to OpenMP, |
| this may lead to surprising results, especially to segmentation faults |
| if the stacksize is limited. |
| |
| @item |
| On glibc-based systems, OpenMP enabled applications cannot be statically |
| linked due to limitations of the underlying pthreads-implementation. It |
| might be possible to get a working solution if |
| @command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added |
| to the command line. However, this is not supported by @command{gcc} and |
| thus not recommended. |
| @end itemize |
| |
| @node OpenACC |
| @subsection OpenACC |
| @cindex OpenACC |
| |
| OpenACC is an application programming interface (API) that supports |
| offloading of code to accelerator devices. It consists of a set of |
| compiler directives, library routines, and environment variables that |
| influence run-time behavior. |
| |
| GNU Fortran strives to be compatible to the |
| @uref{https://www.openacc.org/, OpenACC Application Programming |
| Interface v2.6}. |
| |
| To enable the processing of the OpenACC directive @code{!$acc} in |
| free-form source code; the @code{c$acc}, @code{*$acc} and @code{!$acc} |
| directives in fixed form; the @code{!$} conditional compilation |
| sentinels in free form; and the @code{c$}, @code{*$} and @code{!$} |
| sentinels in fixed form, @command{gfortran} needs to be invoked with |
| the @option{-fopenacc}. This also arranges for automatic linking of |
| the GNU Offloading and Multi Processing Runtime Library |
| @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime |
| Library}. |
| |
| The OpenACC Fortran runtime library routines are provided both in a |
| form of a Fortran 90 module named @code{openacc} and in a form of a |
| Fortran @code{include} file named @file{openacc_lib.h}. |
| |
| @node Argument list functions |
| @subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC} |
| @cindex argument list functions |
| @cindex @code{%VAL} |
| @cindex @code{%REF} |
| @cindex @code{%LOC} |
| |
| GNU Fortran supports argument list functions @code{%VAL}, @code{%REF} |
| and @code{%LOC} statements, for backward compatibility with g77. |
| It is recommended that these should be used only for code that is |
| accessing facilities outside of GNU Fortran, such as operating system |
| or windowing facilities. It is best to constrain such uses to isolated |
| portions of a program--portions that deal specifically and exclusively |
| with low-level, system-dependent facilities. Such portions might well |
| provide a portable interface for use by the program as a whole, but are |
| themselves not portable, and should be thoroughly tested each time they |
| are rebuilt using a new compiler or version of a compiler. |
| |
| @code{%VAL} passes a scalar argument by value, @code{%REF} passes it by |
| reference and @code{%LOC} passes its memory location. Since gfortran |
| already passes scalar arguments by reference, @code{%REF} is in effect |
| a do-nothing. @code{%LOC} has the same effect as a Fortran pointer. |
| |
| An example of passing an argument by value to a C subroutine foo.: |
| @smallexample |
| C |
| C prototype void foo_ (float x); |
| C |
| external foo |
| real*4 x |
| x = 3.14159 |
| call foo (%VAL (x)) |
| end |
| @end smallexample |
| |
| For details refer to the g77 manual |
| @uref{https://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}. |
| |
| Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the |
| GNU Fortran testsuite are worth a look. |
| |
| @node Read/Write after EOF marker |
| @subsection Read/Write after EOF marker |
| @cindex @code{EOF} |
| @cindex @code{BACKSPACE} |
| @cindex @code{REWIND} |
| |
| Some legacy codes rely on allowing @code{READ} or @code{WRITE} after the |
| EOF file marker in order to find the end of a file. GNU Fortran normally |
| rejects these codes with a run-time error message and suggests the user |
| consider @code{BACKSPACE} or @code{REWIND} to properly position |
| the file before the EOF marker. As an extension, the run-time error may |
| be disabled using -std=legacy. |
| |
| |
| @node STRUCTURE and RECORD |
| @subsection @code{STRUCTURE} and @code{RECORD} |
| @cindex @code{STRUCTURE} |
| @cindex @code{RECORD} |
| |
| Record structures are a pre-Fortran-90 vendor extension to create |
| user-defined aggregate data types. Support for record structures in GNU |
| Fortran can be enabled with the @option{-fdec-structure} compile flag. |
| If you have a choice, you should instead use Fortran 90's ``derived types'', |
| which have a different syntax. |
| |
| In many cases, record structures can easily be converted to derived types. |
| To convert, replace @code{STRUCTURE /}@var{structure-name}@code{/} |
| by @code{TYPE} @var{type-name}. Additionally, replace |
| @code{RECORD /}@var{structure-name}@code{/} by |
| @code{TYPE(}@var{type-name}@code{)}. Finally, in the component access, |
| replace the period (@code{.}) by the percent sign (@code{%}). |
| |
| Here is an example of code using the non portable record structure syntax: |
| |
| @example |
| ! Declaring a structure named ``item'' and containing three fields: |
| ! an integer ID, an description string and a floating-point price. |
| STRUCTURE /item/ |
| INTEGER id |
| CHARACTER(LEN=200) description |
| REAL price |
| END STRUCTURE |
| |
| ! Define two variables, an single record of type ``item'' |
| ! named ``pear'', and an array of items named ``store_catalog'' |
| RECORD /item/ pear, store_catalog(100) |
| |
| ! We can directly access the fields of both variables |
| pear.id = 92316 |
| pear.description = "juicy D'Anjou pear" |
| pear.price = 0.15 |
| store_catalog(7).id = 7831 |
| store_catalog(7).description = "milk bottle" |
| store_catalog(7).price = 1.2 |
| |
| ! We can also manipulate the whole structure |
| store_catalog(12) = pear |
| print *, store_catalog(12) |
| @end example |
| |
| @noindent |
| This code can easily be rewritten in the Fortran 90 syntax as following: |
| |
| @example |
| ! ``STRUCTURE /name/ ... END STRUCTURE'' becomes |
| ! ``TYPE name ... END TYPE'' |
| TYPE item |
| INTEGER id |
| CHARACTER(LEN=200) description |
| REAL price |
| END TYPE |
| |
| ! ``RECORD /name/ variable'' becomes ``TYPE(name) variable'' |
| TYPE(item) pear, store_catalog(100) |
| |
| ! Instead of using a dot (.) to access fields of a record, the |
| ! standard syntax uses a percent sign (%) |
| pear%id = 92316 |
| pear%description = "juicy D'Anjou pear" |
| pear%price = 0.15 |
| store_catalog(7)%id = 7831 |
| store_catalog(7)%description = "milk bottle" |
| store_catalog(7)%price = 1.2 |
| |
| ! Assignments of a whole variable do not change |
| store_catalog(12) = pear |
| print *, store_catalog(12) |
| @end example |
| |
| @noindent |
| GNU Fortran implements STRUCTURES like derived types with the following |
| rules and exceptions: |
| |
| @itemize @bullet |
| @item Structures act like derived types with the @code{SEQUENCE} attribute. |
| Otherwise they may contain no specifiers. |
| |
| @item Structures may contain a special field with the name @code{%FILL}. |
| This will create an anonymous component which cannot be accessed but occupies |
| space just as if a component of the same type was declared in its place, useful |
| for alignment purposes. As an example, the following structure will consist |
| of at least sixteen bytes: |
| |
| @smallexample |
| structure /padded/ |
| character(4) start |
| character(8) %FILL |
| character(4) end |
| end structure |
| @end smallexample |
| |
| @item Structures may share names with other symbols. For example, the following |
| is invalid for derived types, but valid for structures: |
| |
| @smallexample |
| structure /header/ |
| ! ... |
| end structure |
| record /header/ header |
| @end smallexample |
| |
| @item Structure types may be declared nested within another parent structure. |
| The syntax is: |
| @smallexample |
| structure /type-name/ |
| ... |
| structure [/<type-name>/] <field-list> |
| ... |
| @end smallexample |
| |
| The type name may be ommitted, in which case the structure type itself is |
| anonymous, and other structures of the same type cannot be instantiated. The |
| following shows some examples: |
| |
| @example |
| structure /appointment/ |
| ! nested structure definition: app_time is an array of two 'time' |
| structure /time/ app_time (2) |
| integer(1) hour, minute |
| end structure |
| character(10) memo |
| end structure |
| |
| ! The 'time' structure is still usable |
| record /time/ now |
| now = time(5, 30) |
| |
| ... |
| |
| structure /appointment/ |
| ! anonymous nested structure definition |
| structure start, end |
| integer(1) hour, minute |
| end structure |
| character(10) memo |
| end structure |
| @end example |
| |
| @item Structures may contain @code{UNION} blocks. For more detail see the |
| section on @ref{UNION and MAP}. |
| |
| @item Structures support old-style initialization of components, like |
| those described in @ref{Old-style variable initialization}. For array |
| initializers, an initializer may contain a repeat specification of the form |
| @code{<literal-integer> * <constant-initializer>}. The value of the integer |
| indicates the number of times to repeat the constant initializer when expanding |
| the initializer list. |
| @end itemize |
| |
| @node UNION and MAP |
| @subsection @code{UNION} and @code{MAP} |
| @cindex @code{UNION} |
| @cindex @code{MAP} |
| |
| Unions are an old vendor extension which were commonly used with the |
| non-standard @ref{STRUCTURE and RECORD} extensions. Use of @code{UNION} and |
| @code{MAP} is automatically enabled with @option{-fdec-structure}. |
| |
| A @code{UNION} declaration occurs within a structure; within the definition of |
| each union is a number of @code{MAP} blocks. Each @code{MAP} shares storage |
| with its sibling maps (in the same union), and the size of the union is the |
| size of the largest map within it, just as with unions in C. The major |
| difference is that component references do not indicate which union or map the |
| component is in (the compiler gets to figure that out). |
| |
| Here is a small example: |
| @smallexample |
| structure /myunion/ |
| union |
| map |
| character(2) w0, w1, w2 |
| end map |
| map |
| character(6) long |
| end map |
| end union |
| end structure |
| |
| record /myunion/ rec |
| ! After this assignment... |
| rec.long = 'hello!' |
| |
| ! The following is true: |
| ! rec.w0 === 'he' |
| ! rec.w1 === 'll' |
| ! rec.w2 === 'o!' |
| @end smallexample |
| |
| The two maps share memory, and the size of the union is ultimately six bytes: |
| |
| @example |
| 0 1 2 3 4 5 6 Byte offset |
| ------------------------------- |
| | | | | | | | |
| ------------------------------- |
| |
| ^ W0 ^ W1 ^ W2 ^ |
| \-------/ \-------/ \-------/ |
| |
| ^ LONG ^ |
| \---------------------------/ |
| @end example |
| |
| Following is an example mirroring the layout of an Intel x86_64 register: |
| |
| @example |
| structure /reg/ |
| union ! U0 ! rax |
| map |
| character(16) rx |
| end map |
| map |
| character(8) rh ! rah |
| union ! U1 |
| map |
| character(8) rl ! ral |
| end map |
| map |
| character(8) ex ! eax |
| end map |
| map |
| character(4) eh ! eah |
| union ! U2 |
| map |
| character(4) el ! eal |
| end map |
| map |
| character(4) x ! ax |
| end map |
| map |
| character(2) h ! ah |
| character(2) l ! al |
| end map |
| end union |
| end map |
| end union |
| end map |
| end union |
| end structure |
| record /reg/ a |
| |
| ! After this assignment... |
| a.rx = 'AAAAAAAA.BBB.C.D' |
| |
| ! The following is true: |
| a.rx === 'AAAAAAAA.BBB.C.D' |
| a.rh === 'AAAAAAAA' |
| a.rl === '.BBB.C.D' |
| a.ex === '.BBB.C.D' |
| a.eh === '.BBB' |
| a.el === '.C.D' |
| a.x === '.C.D' |
| a.h === '.C' |
| a.l === '.D' |
| @end example |
| |
| @node Type variants for integer intrinsics |
| @subsection Type variants for integer intrinsics |
| @cindex intrinsics, integer |
| |
| Similar to the D/C prefixes to real functions to specify the input/output |
| types, GNU Fortran offers B/I/J/K prefixes to integer functions for |
| compatibility with DEC programs. The types implied by each are: |
| |
| @example |
| @code{B} - @code{INTEGER(kind=1)} |
| @code{I} - @code{INTEGER(kind=2)} |
| @code{J} - @code{INTEGER(kind=4)} |
| @code{K} - @code{INTEGER(kind=8)} |
| @end example |
| |
| GNU Fortran supports these with the flag @option{-fdec-intrinsic-ints}. |
| Intrinsics for which prefixed versions are available and in what form are noted |
| in @ref{Intrinsic Procedures}. The complete list of supported intrinsics is |
| here: |
| |
| @multitable @columnfractions .2 .2 .2 .2 .2 |
| |
| @headitem Intrinsic @tab B @tab I @tab J @tab K |
| |
| @item @code{@ref{ABS}} |
| @tab @code{BABS} @tab @code{IIABS} @tab @code{JIABS} @tab @code{KIABS} |
| @item @code{@ref{BTEST}} |
| @tab @code{BBTEST} @tab @code{BITEST} @tab @code{BJTEST} @tab @code{BKTEST} |
| @item @code{@ref{IAND}} |
| @tab @code{BIAND} @tab @code{IIAND} @tab @code{JIAND} @tab @code{KIAND} |
| @item @code{@ref{IBCLR}} |
| @tab @code{BBCLR} @tab @code{IIBCLR} @tab @code{JIBCLR} @tab @code{KIBCLR} |
| @item @code{@ref{IBITS}} |
| @tab @code{BBITS} @tab @code{IIBITS} @tab @code{JIBITS} @tab @code{KIBITS} |
| @item @code{@ref{IBSET}} |
| @tab @code{BBSET} @tab @code{IIBSET} @tab @code{JIBSET} @tab @code{KIBSET} |
| @item @code{@ref{IEOR}} |
| @tab @code{BIEOR} @tab @code{IIEOR} @tab @code{JIEOR} @tab @code{KIEOR} |
| @item @code{@ref{IOR}} |
| @tab @code{BIOR} @tab @code{IIOR} @tab @code{JIOR} @tab @code{KIOR} |
| @item @code{@ref{ISHFT}} |
| @tab @code{BSHFT} @tab @code{IISHFT} @tab @code{JISHFT} @tab @code{KISHFT} |
| @item @code{@ref{ISHFTC}} |
| @tab @code{BSHFTC} @tab @code{IISHFTC} @tab @code{JISHFTC} @tab @code{KISHFTC} |
| @item @code{@ref{MOD}} |
| @tab @code{BMOD} @tab @code{IMOD} @tab @code{JMOD} @tab @code{KMOD} |
| @item @code{@ref{NOT}} |
| @tab @code{BNOT} @tab @code{INOT} @tab @code{JNOT} @tab @code{KNOT} |
| @item @code{@ref{REAL}} |
| @tab @code{--} @tab @code{FLOATI} @tab @code{FLOATJ} @tab @code{FLOATK} |
| @end multitable |
| |
| @node AUTOMATIC and STATIC attributes |
| @subsection @code{AUTOMATIC} and @code{STATIC} attributes |
| @cindex variable attributes |
| @cindex @code{AUTOMATIC} |
| @cindex @code{STATIC} |
| |
| With @option{-fdec-static} GNU Fortran supports the DEC extended attributes |
| @code{STATIC} and @code{AUTOMATIC} to provide explicit specification of entity |
| storage. These follow the syntax of the Fortran standard @code{SAVE} attribute. |
| |
| @code{STATIC} is exactly equivalent to @code{SAVE}, and specifies that |
| an entity should be allocated in static memory. As an example, @code{STATIC} |
| local variables will retain their values across multiple calls to a function. |
| |
| Entities marked @code{AUTOMATIC} will be stack automatic whenever possible. |
| @code{AUTOMATIC} is the default for local variables smaller than |
| @option{-fmax-stack-var-size}, unless @option{-fno-automatic} is given. This |
| attribute overrides @option{-fno-automatic}, @option{-fmax-stack-var-size}, and |
| blanket @code{SAVE} statements. |
| |
| |
| Examples: |
| |
| @example |
| subroutine f |
| integer, automatic :: i ! automatic variable |
| integer x, y ! static variables |
| save |
| ... |
| endsubroutine |
| @end example |
| @example |
| subroutine f |
| integer a, b, c, x, y, z |
| static :: x |
| save y |
| automatic z, c |
| ! a, b, c, and z are automatic |
| ! x and y are static |
| endsubroutine |
| @end example |
| @example |
| ! Compiled with -fno-automatic |
| subroutine f |
| integer a, b, c, d |
| automatic :: a |
| ! a is automatic; b, c, and d are static |
| endsubroutine |
| @end example |
| |
| @node Extended math intrinsics |
| @subsection Extended math intrinsics |
| @cindex intrinsics, math |
| @cindex intrinsics, trigonometric functions |
| |
| GNU Fortran supports an extended list of mathematical intrinsics with the |
| compile flag @option{-fdec-math} for compatability with legacy code. |
| These intrinsics are described fully in @ref{Intrinsic Procedures} where it is |
| noted that they are extensions and should be avoided whenever possible. |
| |
| Specifically, @option{-fdec-math} enables the @ref{COTAN} intrinsic, and |
| trigonometric intrinsics which accept or produce values in degrees instead of |
| radians. Here is a summary of the new intrinsics: |
| |
| @multitable @columnfractions .5 .5 |
| @headitem Radians @tab Degrees |
| @item @code{@ref{ACOS}} @tab @code{@ref{ACOSD}}* |
| @item @code{@ref{ASIN}} @tab @code{@ref{ASIND}}* |
| @item @code{@ref{ATAN}} @tab @code{@ref{ATAND}}* |
| @item @code{@ref{ATAN2}} @tab @code{@ref{ATAN2D}}* |
| @item @code{@ref{COS}} @tab @code{@ref{COSD}}* |
| @item @code{@ref{COTAN}}* @tab @code{@ref{COTAND}}* |
| @item @code{@ref{SIN}} @tab @code{@ref{SIND}}* |
| @item @code{@ref{TAN}} @tab @code{@ref{TAND}}* |
| @end multitable |
| |
| * Enabled with @option{-fdec-math}. |
| |
| For advanced users, it may be important to know the implementation of these |
| functions. They are simply wrappers around the standard radian functions, which |
| have more accurate builtin versions. These functions convert their arguments |
| (or results) to degrees (or radians) by taking the value modulus 360 (or 2*pi) |
| and then multiplying it by a constant radian-to-degree (or degree-to-radian) |
| factor, as appropriate. The factor is computed at compile-time as 180/pi (or |
| pi/180). |
| |
| @node Form feed as whitespace |
| @subsection Form feed as whitespace |
| @cindex form feed whitespace |
| |
| Historically, legacy compilers allowed insertion of form feed characters ('\f', |
| ASCII 0xC) at the beginning of lines for formatted output to line printers, |
| though the Fortran standard does not mention this. GNU Fortran supports the |
| interpretation of form feed characters in source as whitespace for |
| compatibility. |
| |
| @node TYPE as an alias for PRINT |
| @subsection TYPE as an alias for PRINT |
| @cindex type alias print |
| For compatibility, GNU Fortran will interpret @code{TYPE} statements as |
| @code{PRINT} statements with the flag @option{-fdec}. With this flag asserted, |
| the following two examples are equivalent: |
| |
| @smallexample |
| TYPE *, 'hello world' |
| @end smallexample |
| |
| @smallexample |
| PRINT *, 'hello world' |
| @end smallexample |
| |
| @node %LOC as an rvalue |
| @subsection %LOC as an rvalue |
| @cindex LOC |
| Normally @code{%LOC} is allowed only in parameter lists. However the intrinsic |
| function @code{LOC} does the same thing, and is usable as the right-hand-side of |
| assignments. For compatibility, GNU Fortran supports the use of @code{%LOC} as |
| an alias for the builtin @code{LOC} with @option{-std=legacy}. With this |
| feature enabled the following two examples are equivalent: |
| |
| @smallexample |
| integer :: i, l |
| l = %loc(i) |
| call sub(l) |
| @end smallexample |
| |
| @smallexample |
| integer :: i |
| call sub(%loc(i)) |
| @end smallexample |
| |
| @node .XOR. operator |
| @subsection .XOR. operator |
| @cindex operators, xor |
| |
| GNU Fortran supports @code{.XOR.} as a logical operator with @code{-std=legacy} |
| for compatibility with legacy code. @code{.XOR.} is equivalent to |
| @code{.NEQV.}. That is, the output is true if and only if the inputs differ. |
| |
| @node Bitwise logical operators |
| @subsection Bitwise logical operators |
| @cindex logical, bitwise |
| |
| With @option{-fdec}, GNU Fortran relaxes the type constraints on |
| logical operators to allow integer operands, and performs the corresponding |
| bitwise operation instead. This flag is for compatibility only, and should be |
| avoided in new code. Consider: |
| |
| @smallexample |
| INTEGER :: i, j |
| i = z'33' |
| j = z'cc' |
| print *, i .AND. j |
| @end smallexample |
| |
| In this example, compiled with @option{-fdec}, GNU Fortran will |
| replace the @code{.AND.} operation with a call to the intrinsic |
| @code{@ref{IAND}} function, yielding the bitwise-and of @code{i} and @code{j}. |
| |
| Note that this conversion will occur if at least one operand is of integral |
| type. As a result, a logical operand will be converted to an integer when the |
| other operand is an integer in a logical operation. In this case, |
| @code{.TRUE.} is converted to @code{1} and @code{.FALSE.} to @code{0}. |
| |
| Here is the mapping of logical operator to bitwise intrinsic used with |
| @option{-fdec}: |
| |
| @multitable @columnfractions .25 .25 .5 |
| @headitem Operator @tab Intrinsic @tab Bitwise operation |
| @item @code{.NOT.} @tab @code{@ref{NOT}} @tab complement |
| @item @code{.AND.} @tab @code{@ref{IAND}} @tab intersection |
| @item @code{.OR.} @tab @code{@ref{IOR}} @tab union |
| @item @code{.NEQV.} @tab @code{@ref{IEOR}} @tab exclusive or |
| @item @code{.EQV.} @tab @code{@ref{NOT}(@ref{IEOR})} @tab complement of exclusive or |
| @end multitable |
| |
| @node Extended I/O specifiers |
| @subsection Extended I/O specifiers |
| @cindex @code{CARRIAGECONTROL} |
| @cindex @code{READONLY} |
| @cindex @code{SHARE} |
| @cindex @code{SHARED} |
| @cindex @code{NOSHARED} |
| @cindex I/O specifiers |
| |
| GNU Fortran supports the additional legacy I/O specifiers |
| @code{CARRIAGECONTROL}, @code{READONLY}, and @code{SHARE} with the |
| compile flag @option{-fdec}, for compatibility. |
| |
| @table @code |
| @item CARRIAGECONTROL |
| The @code{CARRIAGECONTROL} specifier allows a user to control line |
| termination settings between output records for an I/O unit. The specifier has |
| no meaning for readonly files. When @code{CARRAIGECONTROL} is specified upon |
| opening a unit for formatted writing, the exact @code{CARRIAGECONTROL} setting |
| determines what characters to write between output records. The syntax is: |
| |
| @smallexample |
| OPEN(..., CARRIAGECONTROL=cc) |
| @end smallexample |
| |
| Where @emph{cc} is a character expression that evaluates to one of the |
| following values: |
| |
| @multitable @columnfractions .2 .8 |
| @item @code{'LIST'} @tab One line feed between records (default) |
| @item @code{'FORTRAN'} @tab Legacy interpretation of the first character (see below) |
| @item @code{'NONE'} @tab No separator between records |
| @end multitable |
| |
| With @code{CARRIAGECONTROL='FORTRAN'}, when a record is written, the first |
| character of the input record is not written, and instead determines the output |
| record separator as follows: |
| |
| @multitable @columnfractions .3 .3 .4 |
| @headitem Leading character @tab Meaning @tab Output separating character(s) |
| @item @code{'+'} @tab Overprinting @tab Carriage return only |
| @item @code{'-'} @tab New line @tab Line feed and carriage return |
| @item @code{'0'} @tab Skip line @tab Two line feeds and carriage return |
| @item @code{'1'} @tab New page @tab Form feed and carriage return |
| @item @code{'$'} @tab Prompting @tab Line feed (no carriage return) |
| @item @code{CHAR(0)} @tab Overprinting (no advance) @tab None |
| @end multitable |
| |
| @item READONLY |
| The @code{READONLY} specifier may be given upon opening a unit, and is |
| equivalent to specifying @code{ACTION='READ'}, except that the file may not be |
| deleted on close (i.e. @code{CLOSE} with @code{STATUS="DELETE"}). The syntax |
| is: |
| |
| @smallexample |
| @code{OPEN(..., READONLY)} |
| @end smallexample |
| |
| @item SHARE |
| The @code{SHARE} specifier allows system-level locking on a unit upon opening |
| it for controlled access from multiple processes/threads. The @code{SHARE} |
| specifier has several forms: |
| |
| @smallexample |
| OPEN(..., SHARE=sh) |
| OPEN(..., SHARED) |
| OPEN(..., NOSHARED) |
| @end smallexample |
| |
| Where @emph{sh} in the first form is a character expression that evaluates to |
| a value as seen in the table below. The latter two forms are aliases |
| for particular values of @emph{sh}: |
| |
| @multitable @columnfractions .3 .3 .4 |
| @headitem Explicit form @tab Short form @tab Meaning |
| @item @code{SHARE='DENYRW'} @tab @code{NOSHARED} @tab Exclusive (write) lock |
| @item @code{SHARE='DENYNONE'} @tab @code{SHARED} @tab Shared (read) lock |
| @end multitable |
| |
| In general only one process may hold an exclusive (write) lock for a given file |
| at a time, whereas many processes may hold shared (read) locks for the same |
| file. |
| |
| The behavior of locking may vary with your operating system. On POSIX systems, |
| locking is implemented with @code{fcntl}. Consult your corresponding operating |
| system's manual pages for further details. Locking via @code{SHARE=} is not |
| supported on other systems. |
| |
| @end table |
| |
| @node Legacy PARAMETER statements |
| @subsection Legacy PARAMETER statements |
| @cindex PARAMETER |
| |
| For compatibility, GNU Fortran supports legacy PARAMETER statements without |
| parentheses with @option{-std=legacy}. A warning is emitted if used with |
| @option{-std=gnu}, and an error is acknowledged with a real Fortran standard |
| flag (@option{-std=f95}, etc...). These statements take the following form: |
| |
| @smallexample |
| implicit real (E) |
| parameter e = 2.718282 |
| real c |
| parameter c = 3.0e8 |
| @end smallexample |
| |
| @node Default exponents |
| @subsection Default exponents |
| @cindex exponent |
| |
| For compatibility, GNU Fortran supports a default exponent of zero in real |
| constants with @option{-fdec}. For example, @code{9e} would be |
| interpreted as @code{9e0}, rather than an error. |
| |
| |
| @node Extensions not implemented in GNU Fortran |
| @section Extensions not implemented in GNU Fortran |
| @cindex extensions, not implemented |
| |
| The long history of the Fortran language, its wide use and broad |
| userbase, the large number of different compiler vendors and the lack of |
| some features crucial to users in the first standards have lead to the |
| existence of a number of important extensions to the language. While |
| some of the most useful or popular extensions are supported by the GNU |
| Fortran compiler, not all existing extensions are supported. This section |
| aims at listing these extensions and offering advice on how best make |
| code that uses them running with the GNU Fortran compiler. |
| |
| @c More can be found here: |
| @c -- https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html |
| @c -- the list of Fortran and libgfortran bugs closed as WONTFIX: |
| @c http://tinyurl.com/2u4h5y |
| |
| @menu |
| * ENCODE and DECODE statements:: |
| * Variable FORMAT expressions:: |
| @c * TYPE and ACCEPT I/O Statements:: |
| @c * DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers:: |
| @c * Omitted arguments in procedure call:: |
| * Alternate complex function syntax:: |
| * Volatile COMMON blocks:: |
| * OPEN( ... NAME=):: |
| * Q edit descriptor:: |
| @end menu |
| |
| @node ENCODE and DECODE statements |
| @subsection @code{ENCODE} and @code{DECODE} statements |
| @cindex @code{ENCODE} |
| @cindex @code{DECODE} |
| |
| GNU Fortran does not support the @code{ENCODE} and @code{DECODE} |
| statements. These statements are best replaced by @code{READ} and |
| @code{WRITE} statements involving internal files (@code{CHARACTER} |
| variables and arrays), which have been part of the Fortran standard since |
| Fortran 77. For example, replace a code fragment like |
| |
| @smallexample |
| INTEGER*1 LINE(80) |
| REAL A, B, C |
| c ... Code that sets LINE |
| DECODE (80, 9000, LINE) A, B, C |
| 9000 FORMAT (1X, 3(F10.5)) |
| @end smallexample |
| |
| @noindent |
| with the following: |
| |
| @smallexample |
| CHARACTER(LEN=80) LINE |
| REAL A, B, C |
| c ... Code that sets LINE |
| READ (UNIT=LINE, FMT=9000) A, B, C |
| 9000 FORMAT (1X, 3(F10.5)) |
| @end smallexample |
| |
| Similarly, replace a code fragment like |
| |
| @smallexample |
| INTEGER*1 LINE(80) |
| REAL A, B, C |
| c ... Code that sets A, B and C |
| ENCODE (80, 9000, LINE) A, B, C |
| 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) |
| @end smallexample |
| |
| @noindent |
| with the following: |
| |
| @smallexample |
| CHARACTER(LEN=80) LINE |
| REAL A, B, C |
| c ... Code that sets A, B and C |
| WRITE (UNIT=LINE, FMT=9000) A, B, C |
| 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) |
| @end smallexample |
| |
| |
| @node Variable FORMAT expressions |
| @subsection Variable @code{FORMAT} expressions |
| @cindex @code{FORMAT} |
| |
| A variable @code{FORMAT} expression is format statement which includes |
| angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU |
| Fortran does not support this legacy extension. The effect of variable |
| format expressions can be reproduced by using the more powerful (and |
| standard) combination of internal output and string formats. For example, |
| replace a code fragment like this: |
| |
| @smallexample |
| WRITE(6,20) INT1 |
| 20 FORMAT(I<N+1>) |
| @end smallexample |
| |
| @noindent |
| with the following: |
| |
| @smallexample |
| c Variable declaration |
| CHARACTER(LEN=20) FMT |
| c |
| c Other code here... |
| c |
| WRITE(FMT,'("(I", I0, ")")') N+1 |
| WRITE(6,FMT) INT1 |
| @end smallexample |
| |
| @noindent |
| or with: |
| |
| @smallexample |
| c Variable declaration |
| CHARACTER(LEN=20) FMT |
| c |
| c Other code here... |
| c |
| WRITE(FMT,*) N+1 |
| WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1 |
| @end smallexample |
| |
| |
| @node Alternate complex function syntax |
| @subsection Alternate complex function syntax |
| @cindex Complex function |
| |
| Some Fortran compilers, including @command{g77}, let the user declare |
| complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as |
| well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy |
| extensions. @command{gfortran} accepts the latter form, which is more |
| common, but not the former. |
| |
| |
| @node Volatile COMMON blocks |
| @subsection Volatile @code{COMMON} blocks |
| @cindex @code{VOLATILE} |
| @cindex @code{COMMON} |
| |
| Some Fortran compilers, including @command{g77}, let the user declare |
| @code{COMMON} with the @code{VOLATILE} attribute. This is |
| invalid standard Fortran syntax and is not supported by |
| @command{gfortran}. Note that @command{gfortran} accepts |
| @code{VOLATILE} variables in @code{COMMON} blocks since revision 4.3. |
| |
| |
| @node OPEN( ... NAME=) |
| @subsection @code{OPEN( ... NAME=)} |
| @cindex @code{NAME} |
| |
| Some Fortran compilers, including @command{g77}, let the user declare |
| @code{OPEN( ... NAME=)}. This is |
| invalid standard Fortran syntax and is not supported by |
| @command{gfortran}. @code{OPEN( ... NAME=)} should be replaced |
| with @code{OPEN( ... FILE=)}. |
| |
| @node Q edit descriptor |
| @subsection @code{Q} edit descriptor |
| @cindex @code{Q} edit descriptor |
| |
| Some Fortran compilers provide the @code{Q} edit descriptor, which |
| transfers the number of characters left within an input record into an |
| integer variable. |
| |
| A direct replacement of the @code{Q} edit descriptor is not available |
| in @command{gfortran}. How to replicate its functionality using |
| standard-conforming code depends on what the intent of the original |
| code is. |
| |
| Options to replace @code{Q} may be to read the whole line into a |
| character variable and then counting the number of non-blank |
| characters left using @code{LEN_TRIM}. Another method may be to use |
| formatted stream, read the data up to the position where the @code{Q} |
| descriptor occurred, use @code{INQUIRE} to get the file position, |
| count the characters up to the next @code{NEW_LINE} and then start |
| reading from the position marked previously. |
| |
| |
| @c --------------------------------------------------------------------- |
| @c --------------------------------------------------------------------- |
| @c Mixed-Language Programming |
| @c --------------------------------------------------------------------- |
| |
| @node Mixed-Language Programming |
| @chapter Mixed-Language Programming |
| @cindex Interoperability |
| @cindex Mixed-language programming |
| |
| @menu |
| * Interoperability with C:: |
| * GNU Fortran Compiler Directives:: |
| * Non-Fortran Main Program:: |
| * Naming and argument-passing conventions:: |
| @end menu |
| |
| This chapter is about mixed-language interoperability, but also |
| applies if you link Fortran code compiled by different compilers. In |
| most cases, use of the C Binding features of the Fortran 2003 and |
| later standards is sufficient. |
| |
| For example, it is possible to mix Fortran code with C++ code as well |
| as C, if you declare the interface functions as @code{extern "C"} on |
| the C++ side and @code{BIND(C)} on the Fortran side, and follow the |
| rules for interoperability with C. Note that you cannot manipulate |
| C++ class objects in Fortran or vice versa except as opaque pointers. |
| |
| You can use the @command{gfortran} command to link both Fortran and |
| non-Fortran code into the same program, or you can use @command{gcc} |
| or @command{g++} if you also add an explicit @option{-lgfortran} option |
| to link with the Fortran library. If your main program is written in |
| C or some other language instead of Fortran, see |
| @ref{Non-Fortran Main Program}, below. |
| |
| @node Interoperability with C |
| @section Interoperability with C |
| @cindex interoperability with C |
| @cindex C interoperability |
| |
| @menu |
| * Intrinsic Types:: |
| * Derived Types and struct:: |
| * Interoperable Global Variables:: |
| * Interoperable Subroutines and Functions:: |
| * Working with C Pointers:: |
| * Further Interoperability of Fortran with C:: |
| @end menu |
| |
| Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a |
| standardized way to generate procedure and derived-type |
| declarations and global variables that are interoperable with C |
| (ISO/IEC 9899:1999). The @code{BIND(C)} attribute has been added |
| to inform the compiler that a symbol shall be interoperable with C; |
| also, some constraints are added. Note, however, that not |
| all C features have a Fortran equivalent or vice versa. For instance, |
| neither C's unsigned integers nor C's functions with variable number |
| of arguments have an equivalent in Fortran. |
| |
| Note that array dimensions are reversely ordered in C and that arrays in |
| C always start with index 0 while in Fortran they start by default with |
| 1. Thus, an array declaration @code{A(n,m)} in Fortran matches |
| @code{A[m][n]} in C and accessing the element @code{A(i,j)} matches |
| @code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]}; |
| assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}). |
| |
| @node Intrinsic Types |
| @subsection Intrinsic Types |
| @cindex C intrinsic type interoperability |
| @cindex intrinsic type interoperability with C |
| @cindex interoperability, intrinsic type |
| |
| In order to ensure that exactly the same variable type and kind is used |
| in C and Fortran, you should use the named constants for kind parameters |
| that are defined in the @code{ISO_C_BINDING} intrinsic module. |
| That module contains named constants of character type representing |
| the escaped special characters in C, such as newline. |
| For a list of the constants, see @ref{ISO_C_BINDING}. |
| |
| For logical types, please note that the Fortran standard only guarantees |
| interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind |
| logicals and C99 defines that @code{true} has the value 1 and @code{false} |
| the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL} |
| (with any kind parameter) gives an undefined result. (Passing other integer |
| values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the |
| integer is explicitly or implicitly casted to @code{_Bool}.) |
| |
| @node Derived Types and struct |
| @subsection Derived Types and struct |
| @cindex C derived type and struct interoperability |
| @cindex derived type interoperability with C |
| @cindex interoperability, derived type and struct |
| |
| For compatibility of derived types with @code{struct}, use |
| the @code{BIND(C)} attribute in the type declaration. For instance, the |
| following type declaration |
| |
| @smallexample |
| USE ISO_C_BINDING |
| TYPE, BIND(C) :: myType |
| INTEGER(C_INT) :: i1, i2 |
| INTEGER(C_SIGNED_CHAR) :: i3 |
| REAL(C_DOUBLE) :: d1 |
| COMPLEX(C_FLOAT_COMPLEX) :: c1 |
| CHARACTER(KIND=C_CHAR) :: str(5) |
| END TYPE |
| @end smallexample |
| |
| @noindent |
| matches the following @code{struct} declaration in C |
| |
| @smallexample |
| struct @{ |
| int i1, i2; |
| /* Note: "char" might be signed or unsigned. */ |
| signed char i3; |
| double d1; |
| float _Complex c1; |
| char str[5]; |
| @} myType; |
| @end smallexample |
| |
| Derived types with the C binding attribute shall not have the @code{sequence} |
| attribute, type parameters, the @code{extends} attribute, nor type-bound |
| procedures. Every component must be of interoperable type and kind and may not |
| have the @code{pointer} or @code{allocatable} attribute. The names of the |
| components are irrelevant for interoperability. |
| |
| As there exist no direct Fortran equivalents, neither unions nor structs |
| with bit field or variable-length array members are interoperable. |
| |
| @node Interoperable Global Variables |
| @subsection Interoperable Global Variables |
| @cindex C variable interoperability |
| @cindex variable interoperability with C |
| @cindex interoperability, variable |
| |
| Variables can be made accessible from C using the C binding attribute, |
| optionally together with specifying a binding name. Those variables |
| have to be declared in the declaration part of a @code{MODULE}, |
| be of interoperable type, and have neither the @code{pointer} nor |
| the @code{allocatable} attribute. |
| |
| @smallexample |
| MODULE m |
| USE myType_module |
| USE ISO_C_BINDING |
| integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag |
| type(myType), bind(C) :: tp |
| END MODULE |
| @end smallexample |
| |
| Here, @code{_MyProject_flags} is the case-sensitive name of the variable |
| as seen from C programs while @code{global_flag} is the case-insensitive |
| name as seen from Fortran. If no binding name is specified, as for |
| @var{tp}, the C binding name is the (lowercase) Fortran binding name. |
| If a binding name is specified, only a single variable may be after the |
| double colon. Note of warning: You cannot use a global variable to |
| access @var{errno} of the C library as the C standard allows it to be |
| a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead. |
| |
| @node Interoperable Subroutines and Functions |
| @subsection Interoperable Subroutines and Functions |
| @cindex C procedure interoperability |
| @cindex procedure interoperability with C |
| @cindex function interoperability with C |
| @cindex subroutine interoperability with C |
| @cindex interoperability, subroutine and function |
| |
| Subroutines and functions have to have the @code{BIND(C)} attribute to |
| be compatible with C. The dummy argument declaration is relatively |
| straightforward. However, one needs to be careful because C uses |
| call-by-value by default while Fortran behaves usually similar to |
| call-by-reference. Furthermore, strings and pointers are handled |
| differently. |
| |
| To pass a variable by value, use the @code{VALUE} attribute. |
| Thus, the following C prototype |
| |
| @smallexample |
| @code{int func(int i, int *j)} |
| @end smallexample |
| |
| @noindent |
| matches the Fortran declaration |
| |
| @smallexample |
| integer(c_int) function func(i,j) |
| use iso_c_binding, only: c_int |
| integer(c_int), VALUE :: i |
| integer(c_int) :: j |
| @end smallexample |
| |
| Note that pointer arguments also frequently need the @code{VALUE} attribute, |
| see @ref{Working with C Pointers}. |
| |
| Strings are handled quite differently in C and Fortran. In C a string |
| is a @code{NUL}-terminated array of characters while in Fortran each string |
| has a length associated with it and is thus not terminated (by e.g. |
| @code{NUL}). For example, if you want to use the following C function, |
| |
| @smallexample |
| #include <stdio.h> |
| void print_C(char *string) /* equivalent: char string[] */ |
| @{ |
| printf("%s\n", string); |
| @} |
| @end smallexample |
| |
| @noindent |
| to print ``Hello World'' from Fortran, you can call it using |
| |
| @smallexample |
| use iso_c_binding, only: C_CHAR, C_NULL_CHAR |
| interface |
| subroutine print_c(string) bind(C, name="print_C") |
| use iso_c_binding, only: c_char |
| character(kind=c_char) :: string(*) |
| end subroutine print_c |
| end interface |
| call print_c(C_CHAR_"Hello World"//C_NULL_CHAR) |
| @end smallexample |
| |
| As the example shows, you need to ensure that the |
| string is @code{NUL} terminated. Additionally, the dummy argument |
| @var{string} of @code{print_C} is a length-one assumed-size |
| array; using @code{character(len=*)} is not allowed. The example |
| above uses @code{c_char_"Hello World"} to ensure the string |
| literal has the right type; typically the default character |
| kind and @code{c_char} are the same and thus @code{"Hello World"} |
| is equivalent. However, the standard does not guarantee this. |
| |
| The use of strings is now further illustrated using the C library |
| function @code{strncpy}, whose prototype is |
| |
| @smallexample |
| char *strncpy(char *restrict s1, const char *restrict s2, size_t n); |
| @end smallexample |
| |
| @noindent |
| The function @code{strncpy} copies at most @var{n} characters from |
| string @var{s2} to @var{s1} and returns @var{s1}. In the following |
| example, we ignore the return value: |
| |
| @smallexample |
| use iso_c_binding |
| implicit none |
| character(len=30) :: str,str2 |
| interface |
| ! Ignore the return value of strncpy -> subroutine |
| ! "restrict" is always assumed if we do not pass a pointer |
| subroutine strncpy(dest, src, n) bind(C) |
| import |
| character(kind=c_char), intent(out) :: dest(*) |
| character(kind=c_char), intent(in) :: src(*) |
| integer(c_size_t), value, intent(in) :: n |
| end subroutine strncpy |
| end interface |
| str = repeat('X',30) ! Initialize whole string with 'X' |
| call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, & |
| len(c_char_"Hello World",kind=c_size_t)) |
| print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX" |
| end |
| @end smallexample |
| |
| The intrinsic procedures are described in @ref{Intrinsic Procedures}. |
| |
| @node Working with C Pointers |
| @subsection Working with C Pointers |
| @cindex C pointers |
| @cindex pointers, C |
| |
| C pointers are represented in Fortran via the special opaque derived |
| type @code{type(c_ptr)} (with private components). C pointers are distinct |
| from Fortran objects with the @code{POINTER} attribute. Thus one needs to |
| use intrinsic conversion procedures to convert from or to C pointers. |
| For some applications, using an assumed type (@code{TYPE(*)}) can be |
| an alternative to a C pointer, and you can also use library routines |
| to access Fortran pointers from C. See @ref{Further Interoperability |
| of Fortran with C}. |
| |
| Here is an example of using C pointers in Fortran: |
| |
| @smallexample |
| use iso_c_binding |
| type(c_ptr) :: cptr1, cptr2 |
| integer, target :: array(7), scalar |
| integer, pointer :: pa(:), ps |
| cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the |
| ! array is contiguous if required by the C |
| ! procedure |
| cptr2 = c_loc(scalar) |
| call c_f_pointer(cptr2, ps) |
| call c_f_pointer(cptr2, pa, shape=[7]) |
| @end smallexample |
| |
| When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument |
| has to be passed. |
| |
| If a pointer is a dummy argument of an interoperable procedure, it usually |
| has to be declared using the @code{VALUE} attribute. @code{void*} |
| matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone |
| matches @code{void**}. |
| |
| Procedure pointers are handled analogously to pointers; the C type is |
| @code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are |
| @code{C_F_PROCPOINTER} and @code{C_FUNLOC}. |
| |
| Let us consider two examples of actually passing a procedure pointer from |
| C to Fortran and vice versa. Note that these examples are also very |
| similar to passing ordinary pointers between both languages. First, |
| consider this code in C: |
| |
| @smallexample |
| /* Procedure implemented in Fortran. */ |
| void get_values (void (*)(double)); |
| |
| /* Call-back routine we want called from Fortran. */ |
| void |
| print_it (double x) |
| @{ |
| printf ("Number is %f.\n", x); |
| @} |
| |
| /* Call Fortran routine and pass call-back to it. */ |
| void |
| foobar () |
| @{ |
| get_values (&print_it); |
| @} |
| @end smallexample |
| |
| A matching implementation for @code{get_values} in Fortran, that correctly |
| receives the procedure pointer from C and is able to call it, is given |
| in the following @code{MODULE}: |
| |
| @smallexample |
| MODULE m |
| IMPLICIT NONE |
| |
| ! Define interface of call-back routine. |
| ABSTRACT INTERFACE |
| SUBROUTINE callback (x) |
| USE, INTRINSIC :: ISO_C_BINDING |
| REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x |
| END SUBROUTINE callback |
| END INTERFACE |
| |
| CONTAINS |
| |
| ! Define C-bound procedure. |
| SUBROUTINE get_values (cproc) BIND(C) |
| USE, INTRINSIC :: ISO_C_BINDING |
| TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc |
| |
| PROCEDURE(callback), POINTER :: proc |
| |
| ! Convert C to Fortran procedure pointer. |
| CALL C_F_PROCPOINTER (cproc, proc) |
| |
| ! Call it. |
| CALL proc (1.0_C_DOUBLE) |
| CALL proc (-42.0_C_DOUBLE) |
| CALL proc (18.12_C_DOUBLE) |
| END SUBROUTINE get_values |
| |
| END MODULE m |
| @end smallexample |
| |
| Next, we want to call a C routine that expects a procedure pointer argument |
| and pass it a Fortran procedure (which clearly must be interoperable!). |
| Again, the C function may be: |
| |
| @smallexample |
| int |
| call_it (int (*func)(int), int arg) |
| @{ |
| return func (arg); |
| @} |
| @end smallexample |
| |
| It can be used as in the following Fortran code: |
| |
| @smallexample |
| MODULE m |
| USE, INTRINSIC :: ISO_C_BINDING |
| IMPLICIT NONE |
| |
| ! Define interface of C function. |
| INTERFACE |
| INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C) |
| USE, INTRINSIC :: ISO_C_BINDING |
| TYPE(C_FUNPTR), INTENT(IN), VALUE :: func |
| INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg |
| END FUNCTION call_it |
| END INTERFACE |
| |
| CONTAINS |
| |
| ! Define procedure passed to C function. |
| ! It must be interoperable! |
| INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C) |
| INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg |
| double_it = arg + arg |
| END FUNCTION double_it |
| |
| ! Call C function. |
| SUBROUTINE foobar () |
| TYPE(C_FUNPTR) :: cproc |
| INTEGER(KIND=C_INT) :: i |
| |
| ! Get C procedure pointer. |
| cproc = C_FUNLOC (double_it) |
| |
| ! Use it. |
| DO i = 1_C_INT, 10_C_INT |
| PRINT *, call_it (cproc, i) |
| END DO |
| END SUBROUTINE foobar |
| |
| END MODULE m |
| @end smallexample |
| |
| @node Further Interoperability of Fortran with C |
| @subsection Further Interoperability of Fortran with C |
| @cindex Further Interoperability of Fortran with C |
| @cindex TS 29113 |
| @cindex array descriptor |
| @cindex dope vector |
| @cindex assumed-type |
| @cindex assumed-rank |
| |
| GNU Fortran implements the Technical Specification ISO/IEC TS |
| 29113:2012, which extends the interoperability support of Fortran 2003 |
| and Fortran 2008 and is now part of the 2018 Fortran standard. |
| Besides removing some restrictions and constraints, the Technical |
| Specification adds assumed-type (@code{TYPE(*)}) and assumed-rank |
| (@code{DIMENSION(..)}) variables and allows for interoperability of |
| assumed-shape, assumed-rank, and deferred-shape arrays, as well as |
| allocatables and pointers. Objects of these types are passed to |
| @code{BIND(C)} functions as descriptors with a standard interface, |
| declared in the header file @code{<ISO_Fortran_binding.h>}. |
| |
| Note: Currently, GNU Fortran does not use internally the array descriptor |
| (dope vector) as specified in the Technical Specification, but uses |
| an array descriptor with different fields in functions without the |
| @code{BIND(C)} attribute. Arguments to functions marked @code{BIND(C)} |
| are converted to the specified form. If you need to access GNU Fortran's |
| internal array descriptor, you can use the Chasm Language Interoperability |
| Tools, @url{http://chasm-interop.sourceforge.net/}. |
| |
| @node GNU Fortran Compiler Directives |
| @section GNU Fortran Compiler Directives |
| |
| @menu |
| * ATTRIBUTES directive:: |
| * UNROLL directive:: |
| * BUILTIN directive:: |
| * IVDEP directive:: |
| * VECTOR directive:: |
| * NOVECTOR directive:: |
| @end menu |
| |
| @node ATTRIBUTES directive |
| @subsection ATTRIBUTES directive |
| |
| The Fortran standard describes how a conforming program shall |
| behave; however, the exact implementation is not standardized. In order |
| to allow the user to choose specific implementation details, compiler |
| directives can be used to set attributes of variables and procedures |
| which are not part of the standard. Whether a given attribute is |
| supported and its exact effects depend on both the operating system and |
| on the processor; see |
| @ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)} |
| for details. |
| |
| For procedures and procedure pointers, the following attributes can |
| be used to change the calling convention: |
| |
| @itemize |
| @item @code{CDECL} -- standard C calling convention |
| @item @code{STDCALL} -- convention where the called procedure pops the stack |
| @item @code{FASTCALL} -- part of the arguments are passed via registers |
| instead using the stack |
| @end itemize |
| |
| Besides changing the calling convention, the attributes also influence |
| the decoration of the symbol name, e.g., by a leading underscore or by |
| a trailing at-sign followed by the number of bytes on the stack. When |
| assigning a procedure to a procedure pointer, both should use the same |
| calling convention. |
| |
| On some systems, procedures and global variables (module variables and |
| @code{COMMON} blocks) need special handling to be accessible when they |
| are in a shared library. The following attributes are available: |
| |
| @itemize |
| @item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL |
| @item @code{DLLIMPORT} -- reference the function or variable using a |
| global pointer |
| @end itemize |
| |
| For dummy arguments, the @code{NO_ARG_CHECK} attribute can be used; in |
| other compilers, it is also known as @code{IGNORE_TKR}. For dummy arguments |
| with this attribute actual arguments of any type and kind (similar to |
| @code{TYPE(*)}), scalars and arrays of any rank (no equivalent |
| in Fortran standard) are accepted. As with @code{TYPE(*)}, the argument |
| is unlimited polymorphic and no type information is available. |
| Additionally, the argument may only be passed to dummy arguments |
| with the @code{NO_ARG_CHECK} attribute and as argument to the |
| @code{PRESENT} intrinsic function and to @code{C_LOC} of the |
| @code{ISO_C_BINDING} module. |
| |
| Variables with @code{NO_ARG_CHECK} attribute shall be of assumed-type |
| (@code{TYPE(*)}; recommended) or of type @code{INTEGER}, @code{LOGICAL}, |
| @code{REAL} or @code{COMPLEX}. They shall not have the @code{ALLOCATE}, |
| @code{CODIMENSION}, @code{INTENT(OUT)}, @code{POINTER} or @code{VALUE} |
| attribute; furthermore, they shall be either scalar or of assumed-size |
| (@code{dimension(*)}). As @code{TYPE(*)}, the @code{NO_ARG_CHECK} attribute |
| requires an explicit interface. |
| |
| @itemize |
| @item @code{NO_ARG_CHECK} -- disable the type, kind and rank checking |
| @item @code{DEPRECATED} -- print a warning when using a such-tagged |
| deprecated procedure, variable or parameter; the warning can be suppressed |
| with @option{-Wno-deprecated-declarations}. |
| @end itemize |
| |
| |
| The attributes are specified using the syntax |
| |
| @code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list} |
| |
| where in free-form source code only whitespace is allowed before @code{!GCC$} |
| and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall |
| start in the first column. |
| |
| For procedures, the compiler directives shall be placed into the body |
| of the procedure; for variables and procedure pointers, they shall be in |
| the same declaration part as the variable or procedure pointer. |
| |
| |
| @node UNROLL directive |
| @subsection UNROLL directive |
| |
| The syntax of the directive is |
| |
| @code{!GCC$ unroll N} |
| |
| You can use this directive to control how many times a loop should be unrolled. |
| It must be placed immediately before a @code{DO} loop and applies only to the |
| loop that follows. N is an integer constant specifying the unrolling factor. |
| The values of 0 and 1 block any unrolling of the loop. |
| |
| |
| @node BUILTIN directive |
| @subsection BUILTIN directive |
| |
| The syntax of the directive is |
| |
| @code{!GCC$ BUILTIN (B) attributes simd FLAGS IF('target')} |
| |
| You can use this directive to define which middle-end built-ins provide vector |
| implementations. @code{B} is name of the middle-end built-in. @code{FLAGS} |
| are optional and must be either "(inbranch)" or "(notinbranch)". |
| @code{IF} statement is optional and is used to filter multilib ABIs |
| for the built-in that should be vectorized. Example usage: |
| |
| @smallexample |
| !GCC$ builtin (sinf) attributes simd (notinbranch) if('x86_64') |
| @end smallexample |
| |
| The purpose of the directive is to provide an API among the GCC compiler and |
| the GNU C Library which would define vector implementations of math routines. |
| |
| |
| @node IVDEP directive |
| @subsection IVDEP directive |
| |
| The syntax of the directive is |
| |
| @code{!GCC$ ivdep} |
| |
| This directive tells the compiler to ignore vector dependencies in the |
| following loop. It must be placed immediately before a @code{DO} loop |
| and applies only to the loop that follows. |
| |
| Sometimes the compiler may not have sufficient information to decide |
| whether a particular loop is vectorizable due to potential |
| dependencies between iterations. The purpose of the directive is to |
| tell the compiler that vectorization is safe. |
| |
| This directive is intended for annotation of existing code. For new |
| code it is recommended to consider OpenMP SIMD directives as potential |
| alternative. |
| |
| |
| @node VECTOR directive |
| @subsection VECTOR directive |
| |
| The syntax of the directive is |
| |
| @code{!GCC$ vector} |
| |
| This directive tells the compiler to vectorize the following loop. It |
| must be placed immediately before a @code{DO} loop and applies only to |
| the loop that follows. |
| |
| |
| @node NOVECTOR directive |
| @subsection NOVECTOR directive |
| |
| The syntax of the directive is |
| |
| @code{!GCC$ novector} |
| |
| This directive tells the compiler to not vectorize the following loop. |
| It must be placed immediately before a @code{DO} loop and applies only |
| to the loop that follows. |
| |
| |
| @node Non-Fortran Main Program |
| @section Non-Fortran Main Program |
| |
| @menu |
| * _gfortran_set_args:: Save command-line arguments |
| * _gfortran_set_options:: Set library option flags |
| * _gfortran_set_convert:: Set endian conversion |
| * _gfortran_set_record_marker:: Set length of record markers |
| * _gfortran_set_fpe:: Set when a Floating Point Exception should be raised |
| * _gfortran_set_max_subrecord_length:: Set subrecord length |
| @end menu |
| |
| Even if you are doing mixed-language programming, it is very |
| likely that you do not need to know or use the information in this |
| section. Since it is about the internal structure of GNU Fortran, |
| it may also change in GCC minor releases. |
| |
| When you compile a @code{PROGRAM} with GNU Fortran, a function |
| with the name @code{main} (in the symbol table of the object file) |
| is generated, which initializes the libgfortran library and then |
| calls the actual program which uses the name @code{MAIN__}, for |
| historic reasons. If you link GNU Fortran compiled procedures |
| to, e.g., a C or C++ program or to a Fortran program compiled by |
| a different compiler, the libgfortran library is not initialized |
| and thus a few intrinsic procedures do not work properly, e.g. |
| those for obtaining the command-line arguments. |
| |
| Therefore, if your @code{PROGRAM} is not compiled with |
| GNU Fortran and the GNU Fortran compiled procedures require |
| intrinsics relying on the library initialization, you need to |
| initialize the library yourself. Using the default options, |
| gfortran calls @code{_gfortran_set_args} and |
| @code{_gfortran_set_options}. The initialization of the former |
| is needed if the called procedures access the command line |
| (and for backtracing); the latter sets some flags based on the |
| standard chosen or to enable backtracing. In typical programs, |
| it is not necessary to call any initialization function. |
| |
| If your @code{PROGRAM} is compiled with GNU Fortran, you shall |
| not call any of the following functions. The libgfortran |
| initialization functions are shown in C syntax but using C |
| bindings they are also accessible from Fortran. |
| |
| |
| @node _gfortran_set_args |
| @subsection @code{_gfortran_set_args} --- Save command-line arguments |
| @fnindex _gfortran_set_args |
| @cindex libgfortran initialization, set_args |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{_gfortran_set_args} saves the command-line arguments; this |
| initialization is required if any of the command-line intrinsics |
| is called. Additionally, it shall be called if backtracing is |
| enabled (see @code{_gfortran_set_options}). |
| |
| @item @emph{Syntax}: |
| @code{void _gfortran_set_args (int argc, char *argv[])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{argc} @tab number of command line argument strings |
| @item @var{argv} @tab the command-line argument strings; argv[0] |
| is the pathname of the executable itself. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| int main (int argc, char *argv[]) |
| @{ |
| /* Initialize libgfortran. */ |
| _gfortran_set_args (argc, argv); |
| return 0; |
| @} |
| @end smallexample |
| @end table |
| |
| |
| @node _gfortran_set_options |
| @subsection @code{_gfortran_set_options} --- Set library option flags |
| @fnindex _gfortran_set_options |
| @cindex libgfortran initialization, set_options |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{_gfortran_set_options} sets several flags related to the Fortran |
| standard to be used, whether backtracing should be enabled |
| and whether range checks should be performed. The syntax allows for |
| upward compatibility since the number of passed flags is specified; for |
| non-passed flags, the default value is used. See also |
| @pxref{Code Gen Options}. Please note that not all flags are actually |
| used. |
| |
| @item @emph{Syntax}: |
| @code{void _gfortran_set_options (int num, int options[])} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{num} @tab number of options passed |
| @item @var{argv} @tab The list of flag values |
| @end multitable |
| |
| @item @emph{option flag list}: |
| @multitable @columnfractions .15 .70 |
| @item @var{option}[0] @tab Allowed standard; can give run-time errors |
| if e.g. an input-output edit descriptor is invalid in a given |
| standard. Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1), |
| @code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4), |
| @code{GFC_STD_F95} (8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU} |
| (32), @code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128), |
| @code{GFC_STD_F2008_OBS} (256), @code{GFC_STD_F2008_TS} (512), |
| @code{GFC_STD_F2018} (1024), @code{GFC_STD_F2018_OBS} (2048), and |
| @code{GFC_STD=F2018_DEL} (4096). Default: @code{GFC_STD_F95_OBS | |
| GFC_STD_F95_DEL | GFC_STD_F95 | GFC_STD_F2003 | GFC_STD_F2008 | |
| GFC_STD_F2008_TS | GFC_STD_F2008_OBS | GFC_STD_F77 | GFC_STD_F2018 | |
| GFC_STD_F2018_OBS | GFC_STD_F2018_DEL | GFC_STD_GNU | GFC_STD_LEGACY}. |
| @item @var{option}[1] @tab Standard-warning flag; prints a warning to |
| standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}. |
| @item @var{option}[2] @tab If non zero, enable pedantic checking. |
| Default: off. |
| @item @var{option}[3] @tab Unused. |
| @item @var{option}[4] @tab If non zero, enable backtracing on run-time |
| errors. Default: off. (Default in the compiler: on.) |
| Note: Installs a signal handler and requires command-line |
| initialization using @code{_gfortran_set_args}. |
| @item @var{option}[5] @tab If non zero, supports signed zeros. |
| Default: enabled. |
| @item @var{option}[6] @tab Enables run-time checking. Possible values |
| are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2), |
| GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (8), GFC_RTCHECK_POINTER (16), |
| GFC_RTCHECK_MEM (32), GFC_RTCHECK_BITS (64). |
| Default: disabled. |
| @item @var{option}[7] @tab Unused. |
| @item @var{option}[8] @tab Show a warning when invoking @code{STOP} and |
| @code{ERROR STOP} if a floating-point exception occurred. Possible values |
| are (bitwise or-ed) @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2), |
| @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8), |
| @code{GFC_FPE_UNDERFLOW} (16), @code{GFC_FPE_INEXACT} (32). Default: None (0). |
| (Default in the compiler: @code{GFC_FPE_INVALID | GFC_FPE_DENORMAL | |
| GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW}.) |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| /* Use gfortran 4.9 default options. */ |
| static int options[] = @{68, 511, 0, 0, 1, 1, 0, 0, 31@}; |
| _gfortran_set_options (9, &options); |
| @end smallexample |
| @end table |
| |
| |
| @node _gfortran_set_convert |
| @subsection @code{_gfortran_set_convert} --- Set endian conversion |
| @fnindex _gfortran_set_convert |
| @cindex libgfortran initialization, set_convert |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{_gfortran_set_convert} set the representation of data for |
| unformatted files. |
| |
| @item @emph{Syntax}: |
| @code{void _gfortran_set_convert (int conv)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{conv} @tab Endian conversion, possible values: |
| GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1), |
| GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3). |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| int main (int argc, char *argv[]) |
| @{ |
| /* Initialize libgfortran. */ |
| _gfortran_set_args (argc, argv); |
| _gfortran_set_convert (1); |
| return 0; |
| @} |
| @end smallexample |
| @end table |
| |
| |
| @node _gfortran_set_record_marker |
| @subsection @code{_gfortran_set_record_marker} --- Set length of record markers |
| @fnindex _gfortran_set_record_marker |
| @cindex libgfortran initialization, set_record_marker |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{_gfortran_set_record_marker} sets the length of record markers |
| for unformatted files. |
| |
| @item @emph{Syntax}: |
| @code{void _gfortran_set_record_marker (int val)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{val} @tab Length of the record marker; valid values |
| are 4 and 8. Default is 4. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| int main (int argc, char *argv[]) |
| @{ |
| /* Initialize libgfortran. */ |
| _gfortran_set_args (argc, argv); |
| _gfortran_set_record_marker (8); |
| return 0; |
| @} |
| @end smallexample |
| @end table |
| |
| |
| @node _gfortran_set_fpe |
| @subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps |
| @fnindex _gfortran_set_fpe |
| @cindex libgfortran initialization, set_fpe |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{_gfortran_set_fpe} enables floating point exception traps for |
| the specified exceptions. On most systems, this will result in a |
| SIGFPE signal being sent and the program being aborted. |
| |
| @item @emph{Syntax}: |
| @code{void _gfortran_set_fpe (int val)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{option}[0] @tab IEEE exceptions. Possible values are |
| (bitwise or-ed) zero (0, default) no trapping, |
| @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2), |
| @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8), |
| @code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32). |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| int main (int argc, char *argv[]) |
| @{ |
| /* Initialize libgfortran. */ |
| _gfortran_set_args (argc, argv); |
| /* FPE for invalid operations such as SQRT(-1.0). */ |
| _gfortran_set_fpe (1); |
| return 0; |
| @} |
| @end smallexample |
| @end table |
| |
| |
| @node _gfortran_set_max_subrecord_length |
| @subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length |
| @fnindex _gfortran_set_max_subrecord_length |
| @cindex libgfortran initialization, set_max_subrecord_length |
| |
| @table @asis |
| @item @emph{Description}: |
| @code{_gfortran_set_max_subrecord_length} set the maximum length |
| for a subrecord. This option only makes sense for testing and |
| debugging of unformatted I/O. |
| |
| @item @emph{Syntax}: |
| @code{void _gfortran_set_max_subrecord_length (int val)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{val} @tab the maximum length for a subrecord; |
| the maximum permitted value is 2147483639, which is also |
| the default. |
| @end multitable |
| |
| @item @emph{Example}: |
| @smallexample |
| int main (int argc, char *argv[]) |
| @{ |
| /* Initialize libgfortran. */ |
| _gfortran_set_args (argc, argv); |
| _gfortran_set_max_subrecord_length (8); |
| return 0; |
| @} |
| @end smallexample |
| @end table |
| |
| |
| @node Naming and argument-passing conventions |
| @section Naming and argument-passing conventions |
| |
| This section gives an overview about the naming convention of procedures |
| and global variables and about the argument passing conventions used by |
| GNU Fortran. If a C binding has been specified, the naming convention |
| and some of the argument-passing conventions change. If possible, |
| mixed-language and mixed-compiler projects should use the better defined |
| C binding for interoperability. See @pxref{Interoperability with C}. |
| |
| @menu |
| * Naming conventions:: |
| * Argument passing conventions:: |
| @end menu |
| |
| |
| @node Naming conventions |
| @subsection Naming conventions |
| |
| According the Fortran standard, valid Fortran names consist of a letter |
| between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0}, |
| @code{1} to @code{9} and underscores (@code{_}) with the restriction |
| that names may only start with a letter. As vendor extension, the |
| dollar sign (@code{$}) is additionally permitted with the option |
| @option{-fdollar-ok}, but not as first character and only if the |
| target system supports it. |
| |
| By default, the procedure name is the lower-cased Fortran name with an |
| appended underscore (@code{_}); using @option{-fno-underscoring} no |
| underscore is appended while @code{-fsecond-underscore} appends two |
| underscores. Depending on the target system and the calling convention, |
| the procedure might be additionally dressed; for instance, on 32bit |
| Windows with @code{stdcall}, an at-sign @code{@@} followed by an integer |
| number is appended. For the changing the calling convention, see |
| @pxref{GNU Fortran Compiler Directives}. |
| |
| For common blocks, the same convention is used, i.e. by default an |
| underscore is appended to the lower-cased Fortran name. Blank commons |
| have the name @code{__BLNK__}. |
| |
| For procedures and variables declared in the specification space of a |
| module, the name is formed by @code{__}, followed by the lower-cased |
| module name, @code{_MOD_}, and the lower-cased Fortran name. Note that |
| no underscore is appended. |
| |
| |
| @node Argument passing conventions |
| @subsection Argument passing conventions |
| |
| Subroutines do not return a value (matching C99's @code{void}) while |
| functions either return a value as specified in the platform ABI or |
| the result variable is passed as hidden argument to the function and |
| no result is returned. A hidden result variable is used when the |
| result variable is an array or of type @code{CHARACTER}. |
| |
| Arguments are passed according to the platform ABI. In particular, |
| complex arguments might not be compatible to a struct with two real |
| components for the real and imaginary part. The argument passing |
| matches the one of C99's @code{_Complex}. Functions with scalar |
| complex result variables return their value and do not use a |
| by-reference argument. Note that with the @option{-ff2c} option, |
| the argument passing is modified and no longer completely matches |
| the platform ABI. Some other Fortran compilers use @code{f2c} |
| semantic by default; this might cause problems with |
| interoperablility. |
| |
| GNU Fortran passes most arguments by reference, i.e. by passing a |
| pointer to the data. Note that the compiler might use a temporary |
| variable into which the actual argument has been copied, if required |
| semantically (copy-in/copy-out). |
| |
| For arguments with @code{ALLOCATABLE} and @code{POINTER} |
| attribute (including procedure pointers), a pointer to the pointer |
| is passed such that the pointer address can be modified in the |
| procedure. |
| |
| For dummy arguments with the @code{VALUE} attribute: Scalar arguments |
| of the type @code{INTEGER}, @code{LOGICAL}, @code{REAL} and |
| @code{COMPLEX} are passed by value according to the platform ABI. |
| (As vendor extension and not recommended, using @code{%VAL()} in the |
| call to a procedure has the same effect.) For @code{TYPE(C_PTR)} and |
| procedure pointers, the pointer itself is passed such that it can be |
| modified without affecting the caller. |
| @c FIXME: Document how VALUE is handled for CHARACTER, TYPE, |
| @c CLASS and arrays, i.e. whether the copy-in is done in the caller |
| @c or in the callee. |
| |
| For Boolean (@code{LOGICAL}) arguments, please note that GCC expects |
| only the integer value 0 and 1. If a GNU Fortran @code{LOGICAL} |
| variable contains another integer value, the result is undefined. |
| As some other Fortran compilers use @math{-1} for @code{.TRUE.}, |
| extra care has to be taken -- such as passing the value as |
| @code{INTEGER}. (The same value restriction also applies to other |
| front ends of GCC, e.g. to GCC's C99 compiler for @code{_Bool} |
| or GCC's Ada compiler for @code{Boolean}.) |
| |
| For arguments of @code{CHARACTER} type, the character length is passed |
| as a hidden argument at the end of the argument list. For |
| deferred-length strings, the value is passed by reference, otherwise |
| by value. The character length has the C type @code{size_t} (or |
| @code{INTEGER(kind=C_SIZE_T)} in Fortran). Note that this is |
| different to older versions of the GNU Fortran compiler, where the |
| type of the hidden character length argument was a C @code{int}. In |
| order to retain compatibility with older versions, one can e.g. for |
| the following Fortran procedure |
| |
| @smallexample |
| subroutine fstrlen (s, a) |
| character(len=*) :: s |
| integer :: a |
| print*, len(s) |
| end subroutine fstrlen |
| @end smallexample |
| |
| define the corresponding C prototype as follows: |
| |
| @smallexample |
| #if __GNUC__ > 7 |
| typedef size_t fortran_charlen_t; |
| #else |
| typedef int fortran_charlen_t; |
| #endif |
| |
| void fstrlen_ (char*, int*, fortran_charlen_t); |
| @end smallexample |
| |
| In order to avoid such compiler-specific details, for new code it is |
| instead recommended to use the ISO_C_BINDING feature. |
| |
| Note with C binding, @code{CHARACTER(len=1)} result variables are |
| returned according to the platform ABI and no hidden length argument |
| is used for dummy arguments; with @code{VALUE}, those variables are |
| passed by value. |
| |
| For @code{OPTIONAL} dummy arguments, an absent argument is denoted |
| by a NULL pointer, except for scalar dummy arguments of intrinsic type |
| which have the @code{VALUE} attribute. For those, a hidden Boolean |
| argument (@code{logical(kind=C_bool),value}) is used to indicate |
| whether the argument is present. |
| |
| Arguments which are assumed-shape, assumed-rank or deferred-rank |
| arrays or, with @option{-fcoarray=lib}, allocatable scalar coarrays use |
| an array descriptor. All other arrays pass the address of the |
| first element of the array. With @option{-fcoarray=lib}, the token |
| and the offset belonging to nonallocatable coarrays dummy arguments |
| are passed as hidden argument along the character length hidden |
| arguments. The token is an opaque pointer identifying the coarray |
| and the offset is a passed-by-value integer of kind @code{C_PTRDIFF_T}, |
| denoting the byte offset between the base address of the coarray and |
| the passed scalar or first element of the passed array. |
| |
| The arguments are passed in the following order |
| @itemize @bullet |
| @item Result variable, when the function result is passed by reference |
| @item Character length of the function result, if it is a of type |
| @code{CHARACTER} and no C binding is used |
| @item The arguments in the order in which they appear in the Fortran |
| declaration |
| @item The present status for optional arguments with value attribute, |
| which are internally passed by value |
| @item The character length and/or coarray token and offset for the first |
| argument which is a @code{CHARACTER} or a nonallocatable coarray dummy |
| argument, followed by the hidden arguments of the next dummy argument |
| of such a type |
| @end itemize |
| |
| |
| @c --------------------------------------------------------------------- |
| @c Coarray Programming |
| @c --------------------------------------------------------------------- |
| |
| @node Coarray Programming |
| @chapter Coarray Programming |
| @cindex Coarrays |
| |
| @menu |
| * Type and enum ABI Documentation:: |
| * Function ABI Documentation:: |
| @end menu |
| |
| |
| @node Type and enum ABI Documentation |
| @section Type and enum ABI Documentation |
| |
| @menu |
| * caf_token_t:: |
| * caf_register_t:: |
| * caf_deregister_t:: |
| * caf_reference_t:: |
| * caf_team_t:: |
| @end menu |
| |
| @node caf_token_t |
| @subsection @code{caf_token_t} |
| |
| Typedef of type @code{void *} on the compiler side. Can be any data |
| type on the library side. |
| |
| @node caf_register_t |
| @subsection @code{caf_register_t} |
| |
| Indicates which kind of coarray variable should be registered. |
| |
| @verbatim |
| typedef enum caf_register_t { |
| CAF_REGTYPE_COARRAY_STATIC, |
| CAF_REGTYPE_COARRAY_ALLOC, |
| CAF_REGTYPE_LOCK_STATIC, |
| CAF_REGTYPE_LOCK_ALLOC, |
| CAF_REGTYPE_CRITICAL, |
| CAF_REGTYPE_EVENT_STATIC, |
| CAF_REGTYPE_EVENT_ALLOC, |
| CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY, |
| CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY |
| } |
| caf_register_t; |
| @end verbatim |
| |
| The values @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and |
| @code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} are for allocatable components |
| in derived type coarrays only. The first one sets up the token without |
| allocating memory for allocatable component. The latter one only allocates the |
| memory for an allocatable component in a derived type coarray. The token |
| needs to be setup previously by the REGISTER_ONLY. This allows to have |
| allocatable components un-allocated on some images. The status whether an |
| allocatable component is allocated on a remote image can be queried by |
| @code{_caf_is_present} which used internally by the @code{ALLOCATED} |
| intrinsic. |
| |
| @node caf_deregister_t |
| @subsection @code{caf_deregister_t} |
| |
| @verbatim |
| typedef enum caf_deregister_t { |
| CAF_DEREGTYPE_COARRAY_DEREGISTER, |
| CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY |
| } |
| caf_deregister_t; |
| @end verbatim |
| |
| Allows to specifiy the type of deregistration of a coarray object. The |
| @code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} flag is only allowed for |
| allocatable components in derived type coarrays. |
| |
| @node caf_reference_t |
| @subsection @code{caf_reference_t} |
| |
| The structure used for implementing arbitrary reference chains. |
| A @code{CAF_REFERENCE_T} allows to specify a component reference or any kind |
| of array reference of any rank supported by gfortran. For array references all |
| kinds as known by the compiler/Fortran standard are supported indicated by |
| a @code{MODE}. |
| |
| @verbatim |
| typedef enum caf_ref_type_t { |
| /* Reference a component of a derived type, either regular one or an |
| allocatable or pointer type. For regular ones idx in caf_reference_t is |
| set to -1. */ |
| CAF_REF_COMPONENT, |
| /* Reference an allocatable array. */ |
| CAF_REF_ARRAY, |
| /* Reference a non-allocatable/non-pointer array. I.e., the coarray object |
| has no array descriptor associated and the addressing is done |
| completely using the ref. */ |
| CAF_REF_STATIC_ARRAY |
| } caf_ref_type_t; |
| @end verbatim |
| |
| @verbatim |
| typedef enum caf_array_ref_t { |
| /* No array ref. This terminates the array ref. */ |
| CAF_ARR_REF_NONE = 0, |
| /* Reference array elements given by a vector. Only for this mode |
| caf_reference_t.u.a.dim[i].v is valid. */ |
| CAF_ARR_REF_VECTOR, |
| /* A full array ref (:). */ |
| CAF_ARR_REF_FULL, |
| /* Reference a range on elements given by start, end and stride. */ |
| CAF_ARR_REF_RANGE, |
| /* Only a single item is referenced given in the start member. */ |
| CAF_ARR_REF_SINGLE, |
| /* An array ref of the kind (i:), where i is an arbitrary valid index in the |
| array. The index i is given in the start member. */ |
| CAF_ARR_REF_OPEN_END, |
| /* An array ref of the kind (:i), where the lower bound of the array ref |
| is given by the remote side. The index i is given in the end member. */ |
| CAF_ARR_REF_OPEN_START |
| } caf_array_ref_t; |
| @end verbatim |
| |
| @verbatim |
| /* References to remote components of a derived type. */ |
| typedef struct caf_reference_t { |
| /* A pointer to the next ref or NULL. */ |
| struct caf_reference_t *next; |
| /* The type of the reference. */ |
| /* caf_ref_type_t, replaced by int to allow specification in fortran FE. */ |
| int type; |
| /* The size of an item referenced in bytes. I.e. in an array ref this is |
| the factor to advance the array pointer with to get to the next item. |
| For component refs this gives just the size of the element referenced. */ |
| size_t item_size; |
| union { |
| struct { |
| /* The offset (in bytes) of the component in the derived type. |
| Unused for allocatable or pointer components. */ |
| ptrdiff_t offset; |
| /* The offset (in bytes) to the caf_token associated with this |
| component. NULL, when not allocatable/pointer ref. */ |
| ptrdiff_t caf_token_offset; |
| } c; |
| struct { |
| /* The mode of the array ref. See CAF_ARR_REF_*. */ |
| /* caf_array_ref_t, replaced by unsigend char to allow specification in |
| fortran FE. */ |
| unsigned char mode[GFC_MAX_DIMENSIONS]; |
| /* The type of a static array. Unset for array's with descriptors. */ |
| int static_array_type; |
| /* Subscript refs (s) or vector refs (v). */ |
| union { |
| struct { |
| /* The start and end boundary of the ref and the stride. */ |
| index_type start, end, stride; |
| } s; |
| struct { |
| /* nvec entries of kind giving the elements to reference. */ |
| void *vector; |
| /* The number of entries in vector. */ |
| size_t nvec; |
| /* The integer kind used for the elements in vector. */ |
| int kind; |
| } v; |
| } dim[GFC_MAX_DIMENSIONS]; |
| } a; |
| } u; |
| } caf_reference_t; |
| @end verbatim |
| |
| The references make up a single linked list of reference operations. The |
| @code{NEXT} member links to the next reference or NULL to indicate the end of |
| the chain. Component and array refs can be arbitrarily mixed as long as they |
| comply to the Fortran standard. |
| |
| @emph{NOTES} |
| The member @code{STATIC_ARRAY_TYPE} is used only when the @code{TYPE} is |
| @code{CAF_REF_STATIC_ARRAY}. The member gives the type of the data referenced. |
| Because no array descriptor is available for a descriptor-less array and |
| type conversion still needs to take place the type is transported here. |
| |
| At the moment @code{CAF_ARR_REF_VECTOR} is not implemented in the front end for |
| descriptor-less arrays. The library caf_single has untested support for it. |
| |
| @node caf_team_t |
| @subsection @code{caf_team_t} |
| |
| Opaque pointer to represent a team-handle. This type is a stand-in for the |
| future implementation of teams. It is about to change without further notice. |
| |
| @node Function ABI Documentation |
| @section Function ABI Documentation |
| |
| @menu |
| * _gfortran_caf_init:: Initialiation function |
| * _gfortran_caf_finish:: Finalization function |
| * _gfortran_caf_this_image:: Querying the image number |
| * _gfortran_caf_num_images:: Querying the maximal number of images |
| * _gfortran_caf_image_status :: Query the status of an image |
| * _gfortran_caf_failed_images :: Get an array of the indexes of the failed images |
| * _gfortran_caf_stopped_images :: Get an array of the indexes of the stopped images |
| * _gfortran_caf_register:: Registering coarrays |
| * _gfortran_caf_deregister:: Deregistering coarrays |
| * _gfortran_caf_is_present:: Query whether an allocatable or pointer component in a derived type coarray is allocated |
| * _gfortran_caf_send:: Sending data from a local image to a remote image |
| * _gfortran_caf_get:: Getting data from a remote image |
| * _gfortran_caf_sendget:: Sending data between remote images |
| * _gfortran_caf_send_by_ref:: Sending data from a local image to a remote image using enhanced references |
| * _gfortran_caf_get_by_ref:: Getting data from a remote image using enhanced references |
| * _gfortran_caf_sendget_by_ref:: Sending data between remote images using enhanced references |
| * _gfortran_caf_lock:: Locking a lock variable |
| * _gfortran_caf_unlock:: Unlocking a lock variable |
| * _gfortran_caf_event_post:: Post an event |
| * _gfortran_caf_event_wait:: Wait that an event occurred |
| * _gfortran_caf_event_query:: Query event count |
| * _gfortran_caf_sync_all:: All-image barrier |
| * _gfortran_caf_sync_images:: Barrier for selected images |
| * _gfortran_caf_sync_memory:: Wait for completion of segment-memory operations |
| * _gfortran_caf_error_stop:: Error termination with exit code |
| * _gfortran_caf_error_stop_str:: Error termination with string |
| * _gfortran_caf_fail_image :: Mark the image failed and end its execution |
| * _gfortran_caf_atomic_define:: Atomic variable assignment |
| * _gfortran_caf_atomic_ref:: Atomic variable reference |
| * _gfortran_caf_atomic_cas:: Atomic compare and swap |
| * _gfortran_caf_atomic_op:: Atomic operation |
| * _gfortran_caf_co_broadcast:: Sending data to all images |
| * _gfortran_caf_co_max:: Collective maximum reduction |
| * _gfortran_caf_co_min:: Collective minimum reduction |
| * _gfortran_caf_co_sum:: Collective summing reduction |
| * _gfortran_caf_co_reduce:: Generic collective reduction |
| @end menu |
| |
| |
| @node _gfortran_caf_init |
| @subsection @code{_gfortran_caf_init} --- Initialiation function |
| @cindex Coarray, _gfortran_caf_init |
| |
| @table @asis |
| @item @emph{Description}: |
| This function is called at startup of the program before the Fortran main |
| program, if the latter has been compiled with @option{-fcoarray=lib}. |
| It takes as arguments the command-line arguments of the program. It is |
| permitted to pass two @code{NULL} pointers as argument; if non-@code{NULL}, |
| the library is permitted to modify the arguments. |
| |
| @item @emph{Syntax}: |
| @code{void _gfortran_caf_init (int *argc, char ***argv)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{argc} @tab intent(inout) An integer pointer with the number of |
| arguments passed to the program or @code{NULL}. |
| @item @var{argv} @tab intent(inout) A pointer to an array of strings with the |
| command-line arguments or @code{NULL}. |
| @end multitable |
| |
| @item @emph{NOTES} |
| The function is modelled after the initialization function of the Message |
| Passing Interface (MPI) specification. Due to the way coarray registration |
| works, it might not be the first call to the library. If the main program is |
| not written in Fortran and only a library uses coarrays, it can happen that |
| this function is never called. Therefore, it is recommended that the library |
| does not rely on the passed arguments and whether the call has been done. |
| @end table |
| |
| |
| @node _gfortran_caf_finish |
| @subsection @code{_gfortran_caf_finish} --- Finalization function |
| @cindex Coarray, _gfortran_caf_finish |
| |
| @table @asis |
| @item @emph{Description}: |
| This function is called at the end of the Fortran main program, if it has |
| been compiled with the @option{-fcoarray=lib} option. |
| |
| @item @emph{Syntax}: |
| @code{void _gfortran_caf_finish (void)} |
| |
| @item @emph{NOTES} |
| For non-Fortran programs, it is recommended to call the function at the end |
| of the main program. To ensure that the shutdown is also performed for |
| programs where this function is not explicitly invoked, for instance |
| non-Fortran programs or calls to the system's exit() function, the library |
| can use a destructor function. Note that programs can also be terminated |
| using the STOP and ERROR STOP statements; those use different library calls. |
| @end table |
| |
| |
| @node _gfortran_caf_this_image |
| @subsection @code{_gfortran_caf_this_image} --- Querying the image number |
| @cindex Coarray, _gfortran_caf_this_image |
| |
| @table @asis |
| @item @emph{Description}: |
| This function returns the current image number, which is a positive number. |
| |
| @item @emph{Syntax}: |
| @code{int _gfortran_caf_this_image (int distance)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{distance} @tab As specified for the @code{this_image} intrinsic |
| in TS18508. Shall be a non-negative number. |
| @end multitable |
| |
| @item @emph{NOTES} |
| If the Fortran intrinsic @code{this_image} is invoked without an argument, which |
| is the only permitted form in Fortran 2008, GCC passes @code{0} as |
| first argument. |
| @end table |
| |
| |
| @node _gfortran_caf_num_images |
| @subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images |
| @cindex Coarray, _gfortran_caf_num_images |
| |
| @table @asis |
| @item @emph{Description}: |
| This function returns the number of images in the current team, if |
| @var{distance} is 0 or the number of images in the parent team at the specified |
| distance. If failed is -1, the function returns the number of all images at |
| the specified distance; if it is 0, the function returns the number of |
| nonfailed images, and if it is 1, it returns the number of failed images. |
| |
| @item @emph{Syntax}: |
| @code{int _gfortran_caf_num_images(int distance, int failed)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{distance} @tab the distance from this image to the ancestor. |
| Shall be positive. |
| @item @var{failed} @tab shall be -1, 0, or 1 |
| @end multitable |
| |
| @item @emph{NOTES} |
| This function follows TS18508. If the num_image intrinsic has no arguments, |
| then the compiler passes @code{distance=0} and @code{failed=-1} to the function. |
| @end table |
| |
| |
| @node _gfortran_caf_image_status |
| @subsection @code{_gfortran_caf_image_status} --- Query the status of an image |
| @cindex Coarray, _gfortran_caf_image_status |
| |
| @table @asis |
| @item @emph{Description}: |
| Get the status of the image given by the id @var{image} of the team given by |
| @var{team}. Valid results are zero, for image is ok, @code{STAT_STOPPED_IMAGE} |
| from the ISO_FORTRAN_ENV module to indicate that the image has been stopped and |
| @code{STAT_FAILED_IMAGE} also from ISO_FORTRAN_ENV to indicate that the image |
| has executed a @code{FAIL IMAGE} statement. |
| |
| @item @emph{Syntax}: |
| @code{int _gfortran_caf_image_status (int image, caf_team_t * team)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{image} @tab the positive scalar id of the image in the current TEAM. |
| @item @var{team} @tab optional; team on the which the inquiry is to be |
| performed. |
| @end multitable |
| |
| @item @emph{NOTES} |
| This function follows TS18508. Because team-functionality is not yet |
| implemented a null-pointer is passed for the @var{team} argument at the moment. |
| @end table |
| |
| |
| @node _gfortran_caf_failed_images |
| @subsection @code{_gfortran_caf_failed_images} --- Get an array of the indexes of the failed images |
| @cindex Coarray, _gfortran_caf_failed_images |
| |
| @table @asis |
| @item @emph{Description}: |
| Get an array of image indexes in the current @var{team} that have failed. The |
| array is sorted ascendingly. When @var{team} is not provided the current team |
| is to be used. When @var{kind} is provided then the resulting array is of that |
| integer kind else it is of default integer kind. The returns an unallocated |
| size zero array when no images have failed. |
| |
| @item @emph{Syntax}: |
| @code{int _gfortran_caf_failed_images (caf_team_t * team, int * kind)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{team} @tab optional; team on the which the inquiry is to be |
| performed. |
| @item @var{image} @tab optional; the kind of the resulting integer array. |
| @end multitable |
| |
| @item @emph{NOTES} |
| This function follows TS18508. Because team-functionality is not yet |
| implemented a null-pointer is passed for the @var{team} argument at the moment. |
| @end table |
| |
| |
| @node _gfortran_caf_stopped_images |
| @subsection @code{_gfortran_caf_stopped_images} --- Get an array of the indexes of the stopped images |
| @cindex Coarray, _gfortran_caf_stopped_images |
| |
| @table @asis |
| @item @emph{Description}: |
| Get an array of image indexes in the current @var{team} that have stopped. The |
| array is sorted ascendingly. When @var{team} is not provided the current team |
| is to be used. When @var{kind} is provided then the resulting array is of that |
| integer kind else it is of default integer kind. The returns an unallocated |
| size zero array when no images have failed. |
| |
| @item @emph{Syntax}: |
| @code{int _gfortran_caf_stopped_images (caf_team_t * team, int * kind)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{team} @tab optional; team on the which the inquiry is to be |
| performed. |
| @item @var{image} @tab optional; the kind of the resulting integer array. |
| @end multitable |
| |
| @item @emph{NOTES} |
| This function follows TS18508. Because team-functionality is not yet |
| implemented a null-pointer is passed for the @var{team} argument at the moment. |
| @end table |
| |
| |
| @node _gfortran_caf_register |
| @subsection @code{_gfortran_caf_register} --- Registering coarrays |
| @cindex Coarray, _gfortran_caf_register |
| |
| @table @asis |
| @item @emph{Description}: |
| Registers memory for a coarray and creates a token to identify the coarray. The |
| routine is called for both coarrays with @code{SAVE} attribute and using an |
| explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a |
| @code{NULL} pointer, the function shall abort with printing an error message |
| and starting the error termination. If no error occurs and @var{STAT} is |
| present, it shall be set to zero. Otherwise, it shall be set to a positive |
| value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing |
| the failure. The routine shall register the memory provided in the |
| @code{DATA}-component of the array descriptor @var{DESC}, when that component |
| is non-@code{NULL}, else it shall allocate sufficient memory and provide a |
| pointer to it in the @code{DATA}-component of @var{DESC}. The array descriptor |
| has rank zero, when a scalar object is to be registered and the array |
| descriptor may be invalid after the call to @code{_gfortran_caf_register}. |
| When an array is to be allocated the descriptor persists. |
| |
| For @code{CAF_REGTYPE_COARRAY_STATIC} and @code{CAF_REGTYPE_COARRAY_ALLOC}, |
| the passed size is the byte size requested. For @code{CAF_REGTYPE_LOCK_STATIC}, |
| @code{CAF_REGTYPE_LOCK_ALLOC} and @code{CAF_REGTYPE_CRITICAL} it is the array |
| size or one for a scalar. |
| |
| When @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} is used, then only a token |
| for an allocatable or pointer component is created. The @code{SIZE} parameter |
| is not used then. On the contrary when |
| @code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} is specified, then the |
| @var{token} needs to be registered by a previous call with regtype |
| @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and either the memory specified |
| in the @var{DESC}'s data-ptr is registered or allocate when the data-ptr is |
| @code{NULL}. |
| |
| @item @emph{Syntax}: |
| @code{void caf_register (size_t size, caf_register_t type, caf_token_t *token, |
| gfc_descriptor_t *desc, int *stat, char *errmsg, size_t errmsg_len)} |
| |
| @item @emph{Arguments}: |
| @multitable @columnfractions .15 .70 |
| @item @var{size} @tab For normal coarrays, the byte size of the coarray to be |
| allocated; for lock types and event types, the number of elements. |
|