1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set copyrights-gfortran 1999-2020
6 @include gcc-common.texi
8 @settitle The GNU Fortran Compiler
10 @c Create a separate index for command line options
12 @c Merge the standard indexes into a single one.
19 @c TODO: The following "Part" definitions are included here temporarily
20 @c until they are incorporated into the official Texinfo distribution.
21 @c They borrow heavily from Texinfo's \unnchapentry definitions.
28 \vglue\titlepagetopglue
30 \leftline{Part #1:@* #2}
31 \vskip4pt \hrule height 4pt width \hsize \vskip4pt
33 \writetocentry{part}{#2}{#1}
36 \writetocentry{blankpart}{}{}
38 % Part TOC-entry definition for summary contents.
39 \gdef\dosmallpartentry#1#2#3#4{%
40 \vskip .5\baselineskip plus.2\baselineskip
43 \tocentry{Part #2: #1}{\doshortpageno\bgroup#4\egroup}
46 \gdef\dosmallblankpartentry#1#2#3#4{%
47 \vskip .5\baselineskip plus.2\baselineskip
49 % Part TOC-entry definition for regular contents. This has to be
50 % equated to an existing entry to not cause problems when the PDF
52 \gdef\dopartentry#1#2#3#4{%
53 \unnchapentry{Part #2: #1}{}{#3}{#4}
55 \gdef\doblankpartentry#1#2#3#4{}
60 @c Use with @@smallbook.
62 @c %** start of document
64 @c Cause even numbered pages to be printed on the left hand side of
65 @c the page and odd numbered pages to be printed on the right hand
66 @c side of the page. Using this, you can print on both sides of a
67 @c sheet of paper and have the text on the same part of the sheet.
69 @c The text on right hand pages is pushed towards the right hand
70 @c margin and the text on left hand pages is pushed toward the left
72 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
75 @c \global\bindingoffset=0.75in
76 @c \global\normaloffset =0.75in
80 Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
82 Permission is granted to copy, distribute and/or modify this document
83 under the terms of the GNU Free Documentation License, Version 1.3 or
84 any later version published by the Free Software Foundation; with the
85 Invariant Sections being ``Funding Free Software'', the Front-Cover
86 Texts being (a) (see below), and with the Back-Cover Texts being (b)
87 (see below). A copy of the license is included in the section entitled
88 ``GNU Free Documentation License''.
90 (a) The FSF's Front-Cover Text is:
94 (b) The FSF's Back-Cover Text is:
96 You have freedom to copy and modify this GNU Manual, like GNU
97 software. Copies published by the Free Software Foundation raise
98 funds for GNU development.
102 @dircategory Software development
104 * gfortran: (gfortran). The GNU Fortran Compiler.
106 This file documents the use and the internals of
107 the GNU Fortran compiler, (@command{gfortran}).
109 Published by the Free Software Foundation
110 51 Franklin Street, Fifth Floor
111 Boston, MA 02110-1301 USA
117 @setchapternewpage odd
119 @title Using GNU Fortran
121 @author The @t{gfortran} team
123 @vskip 0pt plus 1filll
124 Published by the Free Software Foundation@*
125 51 Franklin Street, Fifth Floor@*
126 Boston, MA 02110-1301, USA@*
127 @c Last printed ??ber, 19??.@*
128 @c Printed copies are available for $? each.@*
134 @c TODO: The following "Part" definitions are included here temporarily
135 @c until they are incorporated into the official Texinfo distribution.
138 \global\let\partentry=\dosmallpartentry
139 \global\let\blankpartentry=\dosmallblankpartentry
144 \global\let\partentry=\dopartentry
145 \global\let\blankpartentry=\doblankpartentry
151 @c ---------------------------------------------------------------------
152 @c TexInfo table of contents.
153 @c ---------------------------------------------------------------------
160 This manual documents the use of @command{gfortran},
161 the GNU Fortran compiler. You can find in this manual how to invoke
162 @command{gfortran}, as well as its features and incompatibilities.
165 @emph{Warning:} This document, and the compiler it describes, are still
166 under development. While efforts are made to keep it up-to-date, it might
167 not accurately reflect the status of the most recent GNU Fortran compiler.
171 @comment When you add a new menu item, please keep the right hand
172 @comment aligned to the same column. Do not use tabs. This provides
173 @comment better formatting.
178 Part I: Invoking GNU Fortran
179 * Invoking GNU Fortran:: Command options supported by @command{gfortran}.
180 * Runtime:: Influencing runtime behavior with environment variables.
182 Part II: Language Reference
183 * Fortran standards status:: Fortran 2003, 2008 and 2018 features supported by GNU Fortran.
184 * Compiler Characteristics:: User-visible implementation details.
185 * Extensions:: Language extensions implemented by GNU Fortran.
186 * Mixed-Language Programming:: Interoperability with C
187 * Coarray Programming::
188 * Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran.
189 * Intrinsic Modules:: Intrinsic modules supported by GNU Fortran.
191 * Contributing:: How you can help.
192 * Copying:: GNU General Public License says
193 how you can copy and share GNU Fortran.
194 * GNU Free Documentation License::
195 How you can copy and share this manual.
196 * Funding:: How to help assure continued work for free software.
197 * Option Index:: Index of command line options
198 * Keyword Index:: Index of concepts
202 @c ---------------------------------------------------------------------
204 @c ---------------------------------------------------------------------
207 @chapter Introduction
209 @c The following duplicates the text on the TexInfo table of contents.
211 This manual documents the use of @command{gfortran}, the GNU Fortran
212 compiler. You can find in this manual how to invoke @command{gfortran},
213 as well as its features and incompatibilities.
216 @emph{Warning:} This document, and the compiler it describes, are still
217 under development. While efforts are made to keep it up-to-date, it
218 might not accurately reflect the status of the most recent GNU Fortran
223 The GNU Fortran compiler front end was
224 designed initially as a free replacement for,
225 or alternative to, the Unix @command{f95} command;
226 @command{gfortran} is the command you will use to invoke the compiler.
229 * About GNU Fortran:: What you should know about the GNU Fortran compiler.
230 * GNU Fortran and GCC:: You can compile Fortran, C, or other programs.
231 * Preprocessing and conditional compilation:: The Fortran preprocessor
232 * GNU Fortran and G77:: Why we chose to start from scratch.
233 * Project Status:: Status of GNU Fortran, roadmap, proposed extensions.
234 * Standards:: Standards supported by GNU Fortran.
238 @c ---------------------------------------------------------------------
240 @c ---------------------------------------------------------------------
242 @node About GNU Fortran
243 @section About GNU Fortran
245 The GNU Fortran compiler supports the Fortran 77, 90 and 95 standards
246 completely, parts of the Fortran 2003, 2008 and 2018 standards, and
247 several vendor extensions. The development goal is to provide the
252 Read a user's program, stored in a file and containing instructions
253 written in Fortran 77, Fortran 90, Fortran 95, Fortran 2003, Fortran
254 2008 or Fortran 2018. This file contains @dfn{source code}.
257 Translate the user's program into instructions a computer
258 can carry out more quickly than it takes to translate the
259 instructions in the first
260 place. The result after compilation of a program is
262 code designed to be efficiently translated and processed
263 by a machine such as your computer.
264 Humans usually are not as good writing machine code
265 as they are at writing Fortran (or C++, Ada, or Java),
266 because it is easy to make tiny mistakes writing machine code.
269 Provide the user with information about the reasons why
270 the compiler is unable to create a binary from the source code.
271 Usually this will be the case if the source code is flawed.
272 The Fortran 90 standard requires that the compiler can point out
273 mistakes to the user.
274 An incorrect usage of the language causes an @dfn{error message}.
276 The compiler will also attempt to diagnose cases where the
277 user's program contains a correct usage of the language,
278 but instructs the computer to do something questionable.
279 This kind of diagnostics message is called a @dfn{warning message}.
282 Provide optional information about the translation passes
283 from the source code to machine code.
284 This can help a user of the compiler to find the cause of
285 certain bugs which may not be obvious in the source code,
286 but may be more easily found at a lower level compiler output.
287 It also helps developers to find bugs in the compiler itself.
290 Provide information in the generated machine code that can
291 make it easier to find bugs in the program (using a debugging tool,
292 called a @dfn{debugger}, such as the GNU Debugger @command{gdb}).
295 Locate and gather machine code already generated to
296 perform actions requested by statements in the user's program.
297 This machine code is organized into @dfn{modules} and is located
298 and @dfn{linked} to the user program.
301 The GNU Fortran compiler consists of several components:
305 A version of the @command{gcc} command
306 (which also might be installed as the system's @command{cc} command)
307 that also understands and accepts Fortran source code.
308 The @command{gcc} command is the @dfn{driver} program for
309 all the languages in the GNU Compiler Collection (GCC);
311 you can compile the source code of any language for
312 which a front end is available in GCC.
315 The @command{gfortran} command itself,
316 which also might be installed as the
317 system's @command{f95} command.
318 @command{gfortran} is just another driver program,
319 but specifically for the Fortran compiler only.
320 The difference with @command{gcc} is that @command{gfortran}
321 will automatically link the correct libraries to your program.
324 A collection of run-time libraries.
325 These libraries contain the machine code needed to support
326 capabilities of the Fortran language that are not directly
327 provided by the machine code generated by the
328 @command{gfortran} compilation phase,
329 such as intrinsic functions and subroutines,
330 and routines for interaction with files and the operating system.
331 @c and mechanisms to spawn,
332 @c unleash and pause threads in parallelized code.
335 The Fortran compiler itself, (@command{f951}).
336 This is the GNU Fortran parser and code generator,
337 linked to and interfaced with the GCC backend library.
338 @command{f951} ``translates'' the source code to
339 assembler code. You would typically not use this
341 instead, the @command{gcc} or @command{gfortran} driver
342 programs will call it for you.
346 @c ---------------------------------------------------------------------
347 @c GNU Fortran and GCC
348 @c ---------------------------------------------------------------------
350 @node GNU Fortran and GCC
351 @section GNU Fortran and GCC
352 @cindex GNU Compiler Collection
355 GNU Fortran is a part of GCC, the @dfn{GNU Compiler Collection}. GCC
356 consists of a collection of front ends for various languages, which
357 translate the source code into a language-independent form called
358 @dfn{GENERIC}. This is then processed by a common middle end which
359 provides optimization, and then passed to one of a collection of back
360 ends which generate code for different computer architectures and
363 Functionally, this is implemented with a driver program (@command{gcc})
364 which provides the command-line interface for the compiler. It calls
365 the relevant compiler front-end program (e.g., @command{f951} for
366 Fortran) for each file in the source code, and then calls the assembler
367 and linker as appropriate to produce the compiled output. In a copy of
368 GCC which has been compiled with Fortran language support enabled,
369 @command{gcc} will recognize files with @file{.f}, @file{.for}, @file{.ftn},
370 @file{.f90}, @file{.f95}, @file{.f03} and @file{.f08} extensions as
371 Fortran source code, and compile it accordingly. A @command{gfortran}
372 driver program is also provided, which is identical to @command{gcc}
373 except that it automatically links the Fortran runtime libraries into the
376 Source files with @file{.f}, @file{.for}, @file{.fpp}, @file{.ftn}, @file{.F},
377 @file{.FOR}, @file{.FPP}, and @file{.FTN} extensions are treated as fixed form.
378 Source files with @file{.f90}, @file{.f95}, @file{.f03}, @file{.f08},
379 @file{.F90}, @file{.F95}, @file{.F03} and @file{.F08} extensions are
380 treated as free form. The capitalized versions of either form are run
381 through preprocessing. Source files with the lower case @file{.fpp}
382 extension are also run through preprocessing.
384 This manual specifically documents the Fortran front end, which handles
385 the programming language's syntax and semantics. The aspects of GCC
386 which relate to the optimization passes and the back-end code generation
387 are documented in the GCC manual; see
388 @ref{Top,,Introduction,gcc,Using the GNU Compiler Collection (GCC)}.
389 The two manuals together provide a complete reference for the GNU
393 @c ---------------------------------------------------------------------
394 @c Preprocessing and conditional compilation
395 @c ---------------------------------------------------------------------
397 @node Preprocessing and conditional compilation
398 @section Preprocessing and conditional compilation
401 @cindex Conditional compilation
402 @cindex Preprocessing
403 @cindex preprocessor, include file handling
405 Many Fortran compilers including GNU Fortran allow passing the source code
406 through a C preprocessor (CPP; sometimes also called the Fortran preprocessor,
407 FPP) to allow for conditional compilation. In the case of GNU Fortran,
408 this is the GNU C Preprocessor in the traditional mode. On systems with
409 case-preserving file names, the preprocessor is automatically invoked if the
410 filename extension is @file{.F}, @file{.FOR}, @file{.FTN}, @file{.fpp},
411 @file{.FPP}, @file{.F90}, @file{.F95}, @file{.F03} or @file{.F08}. To manually
412 invoke the preprocessor on any file, use @option{-cpp}, to disable
413 preprocessing on files where the preprocessor is run automatically, use
416 If a preprocessed file includes another file with the Fortran @code{INCLUDE}
417 statement, the included file is not preprocessed. To preprocess included
418 files, use the equivalent preprocessor statement @code{#include}.
420 If GNU Fortran invokes the preprocessor, @code{__GFORTRAN__}
421 is defined. The macros @code{__GNUC__}, @code{__GNUC_MINOR__} and
422 @code{__GNUC_PATCHLEVEL__} can be used to determine the version of the
423 compiler. See @ref{Top,,Overview,cpp,The C Preprocessor} for details.
425 GNU Fortran supports a number of @code{INTEGER} and @code{REAL} kind types
426 in additional to the kind types required by the Fortran standard.
427 The availability of any given kind type is architecture dependent. The
428 following pre-defined preprocessor macros can be used to conditionally
429 include code for these additional kind types: @code{__GFC_INT_1__},
430 @code{__GFC_INT_2__}, @code{__GFC_INT_8__}, @code{__GFC_INT_16__},
431 @code{__GFC_REAL_10__}, and @code{__GFC_REAL_16__}.
433 While CPP is the de-facto standard for preprocessing Fortran code,
434 Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines
435 Conditional Compilation, which is not widely used and not directly
436 supported by the GNU Fortran compiler. You can use the program coco
437 to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}).
440 @c ---------------------------------------------------------------------
441 @c GNU Fortran and G77
442 @c ---------------------------------------------------------------------
444 @node GNU Fortran and G77
445 @section GNU Fortran and G77
447 @cindex @command{g77}
449 The GNU Fortran compiler is the successor to @command{g77}, the Fortran
450 77 front end included in GCC prior to version 4. It is an entirely new
451 program that has been designed to provide Fortran 95 support and
452 extensibility for future Fortran language standards, as well as providing
453 backwards compatibility for Fortran 77 and nearly all of the GNU language
454 extensions supported by @command{g77}.
457 @c ---------------------------------------------------------------------
459 @c ---------------------------------------------------------------------
462 @section Project Status
465 As soon as @command{gfortran} can parse all of the statements correctly,
466 it will be in the ``larva'' state.
467 When we generate code, the ``puppa'' state.
468 When @command{gfortran} is done,
469 we'll see if it will be a beautiful butterfly,
470 or just a big bug....
472 --Andy Vaught, April 2000
475 The start of the GNU Fortran 95 project was announced on
476 the GCC homepage in March 18, 2000
477 (even though Andy had already been working on it for a while,
480 The GNU Fortran compiler is able to compile nearly all
481 standard-compliant Fortran 95, Fortran 90, and Fortran 77 programs,
482 including a number of standard and non-standard extensions, and can be
483 used on real-world programs. In particular, the supported extensions
484 include OpenMP, Cray-style pointers, some old vendor extensions, and several
485 Fortran 2003 and Fortran 2008 features, including TR 15581. However, it is
486 still under development and has a few remaining rough edges.
487 There also is initial support for OpenACC.
489 At present, the GNU Fortran compiler passes the
490 @uref{http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html,
491 NIST Fortran 77 Test Suite}, and produces acceptable results on the
492 @uref{http://www.netlib.org/lapack/faq.html#1.21, LAPACK Test Suite}.
493 It also provides respectable performance on
494 the @uref{http://www.polyhedron.com/fortran-compiler-comparisons/polyhedron-benchmark-suite,
496 compiler benchmarks} and the
497 @uref{http://www.netlib.org/benchmark/livermore,
498 Livermore Fortran Kernels test}. It has been used to compile a number of
499 large real-world programs, including
500 @uref{http://hirlam.org/, the HARMONIE and HIRLAM weather forecasting code} and
501 @uref{http://physical-chemistry.scb.uwa.edu.au/tonto/wiki/index.php/Main_Page,
502 the Tonto quantum chemistry package}; see
503 @url{https://gcc.gnu.org/@/wiki/@/GfortranApps} for an extended list.
505 Among other things, the GNU Fortran compiler is intended as a replacement
506 for G77. At this point, nearly all programs that could be compiled with
507 G77 can be compiled with GNU Fortran, although there are a few minor known
510 The primary work remaining to be done on GNU Fortran falls into three
511 categories: bug fixing (primarily regarding the treatment of invalid
512 code and providing useful error messages), improving the compiler
513 optimizations and the performance of compiled code, and extending the
514 compiler to support future standards---in particular, Fortran 2003,
515 Fortran 2008 and Fortran 2018.
518 @c ---------------------------------------------------------------------
520 @c ---------------------------------------------------------------------
527 * Varying Length Character Strings::
530 The GNU Fortran compiler implements
531 ISO/IEC 1539:1997 (Fortran 95). As such, it can also compile essentially all
532 standard-compliant Fortran 90 and Fortran 77 programs. It also supports
533 the ISO/IEC TR-15581 enhancements to allocatable arrays.
535 GNU Fortran also have a partial support for ISO/IEC 1539-1:2004
536 (Fortran 2003), ISO/IEC 1539-1:2010 (Fortran 2008), the Technical
537 Specification @code{Further Interoperability of Fortran with C}
538 (ISO/IEC TS 29113:2012). Full support of those standards and future
539 Fortran standards is planned. The current status of the support is
540 can be found in the @ref{Fortran 2003 status}, @ref{Fortran 2008
541 status} and @ref{Fortran 2018 status} sections of the documentation.
543 Additionally, the GNU Fortran compilers supports the OpenMP specification
544 (version 4.0 and most of the features of the 4.5 version,
545 @url{http://openmp.org/@/wp/@/openmp-specifications/}).
546 There also is support for the OpenACC specification (targeting
547 version 2.6, @uref{http://www.openacc.org/}). See
548 @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
550 @node Varying Length Character Strings
551 @subsection Varying Length Character Strings
552 @cindex Varying length character strings
553 @cindex Varying length strings
554 @cindex strings, varying length
556 The Fortran 95 standard specifies in Part 2 (ISO/IEC 1539-2:2000)
557 varying length character strings. While GNU Fortran currently does not
558 support such strings directly, there exist two Fortran implementations
559 for them, which work with GNU Fortran. They can be found at
560 @uref{http://www.fortran.com/@/iso_varying_string.f95} and at
561 @uref{ftp://ftp.nag.co.uk/@/sc22wg5/@/ISO_VARYING_STRING/}.
563 Deferred-length character strings of Fortran 2003 supports part of
564 the features of @code{ISO_VARYING_STRING} and should be considered as
565 replacement. (Namely, allocatable or pointers of the type
566 @code{character(len=:)}.)
569 @c =====================================================================
570 @c PART I: INVOCATION REFERENCE
571 @c =====================================================================
574 \part{I}{Invoking GNU Fortran}
577 @c ---------------------------------------------------------------------
579 @c ---------------------------------------------------------------------
584 @c ---------------------------------------------------------------------
586 @c ---------------------------------------------------------------------
589 @chapter Runtime: Influencing runtime behavior with environment variables
590 @cindex environment variable
592 The behavior of the @command{gfortran} can be influenced by
593 environment variables.
595 Malformed environment variables are silently ignored.
598 * TMPDIR:: Directory for scratch files
599 * GFORTRAN_STDIN_UNIT:: Unit number for standard input
600 * GFORTRAN_STDOUT_UNIT:: Unit number for standard output
601 * GFORTRAN_STDERR_UNIT:: Unit number for standard error
602 * GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units
603 * GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units.
604 * GFORTRAN_SHOW_LOCUS:: Show location for runtime errors
605 * GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted
606 * GFORTRAN_LIST_SEPARATOR:: Separator for list output
607 * GFORTRAN_CONVERT_UNIT:: Set endianness for unformatted I/O
608 * GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors
609 * GFORTRAN_FORMATTED_BUFFER_SIZE:: Buffer size for formatted files
610 * GFORTRAN_UNFORMATTED_BUFFER_SIZE:: Buffer size for unformatted files
614 @section @env{TMPDIR}---Directory for scratch files
616 When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to
617 create the file in one of the potential directories by testing each
618 directory in the order below.
622 The environment variable @env{TMPDIR}, if it exists.
625 On the MinGW target, the directory returned by the @code{GetTempPath}
626 function. Alternatively, on the Cygwin target, the @env{TMP} and
627 @env{TEMP} environment variables, if they exist, in that order.
630 The @code{P_tmpdir} macro if it is defined, otherwise the directory
634 @node GFORTRAN_STDIN_UNIT
635 @section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input
637 This environment variable can be used to select the unit number
638 preconnected to standard input. This must be a positive integer.
639 The default value is 5.
641 @node GFORTRAN_STDOUT_UNIT
642 @section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output
644 This environment variable can be used to select the unit number
645 preconnected to standard output. This must be a positive integer.
646 The default value is 6.
648 @node GFORTRAN_STDERR_UNIT
649 @section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error
651 This environment variable can be used to select the unit number
652 preconnected to standard error. This must be a positive integer.
653 The default value is 0.
655 @node GFORTRAN_UNBUFFERED_ALL
656 @section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units
658 This environment variable controls whether all I/O is unbuffered. If
659 the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is
660 unbuffered. This will slow down small sequential reads and writes. If
661 the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered.
664 @node GFORTRAN_UNBUFFERED_PRECONNECTED
665 @section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units
667 The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls
668 whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) is unbuffered. If
669 the first letter is @samp{y}, @samp{Y} or @samp{1}, I/O is unbuffered. This
670 will slow down small sequential reads and writes. If the first letter
671 is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. This is the default.
673 @node GFORTRAN_SHOW_LOCUS
674 @section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors
676 If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and
677 line numbers for runtime errors are printed. If the first letter is
678 @samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers
679 for runtime errors. The default is to print the location.
681 @node GFORTRAN_OPTIONAL_PLUS
682 @section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted
684 If the first letter is @samp{y}, @samp{Y} or @samp{1},
685 a plus sign is printed
686 where permitted by the Fortran standard. If the first letter
687 is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed
688 in most cases. Default is not to print plus signs.
690 @node GFORTRAN_LIST_SEPARATOR
691 @section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output
693 This environment variable specifies the separator when writing
694 list-directed output. It may contain any number of spaces and
695 at most one comma. If you specify this on the command line,
696 be sure to quote spaces, as in
698 $ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out
700 when @command{a.out} is the compiled Fortran program that you want to run.
701 Default is a single space.
703 @node GFORTRAN_CONVERT_UNIT
704 @section @env{GFORTRAN_CONVERT_UNIT}---Set endianness for unformatted I/O
706 By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible
707 to change the representation of data for unformatted files.
708 The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable is:
710 GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ;
711 mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ;
712 exception: mode ':' unit_list | unit_list ;
713 unit_list: unit_spec | unit_list unit_spec ;
714 unit_spec: INTEGER | INTEGER '-' INTEGER ;
716 The variable consists of an optional default mode, followed by
717 a list of optional exceptions, which are separated by semicolons
718 from the preceding default and each other. Each exception consists
719 of a format and a comma-separated list of units. Valid values for
720 the modes are the same as for the @code{CONVERT} specifier:
723 @item @code{NATIVE} Use the native format. This is the default.
724 @item @code{SWAP} Swap between little- and big-endian.
725 @item @code{LITTLE_ENDIAN} Use the little-endian format
726 for unformatted files.
727 @item @code{BIG_ENDIAN} Use the big-endian format for unformatted files.
729 A missing mode for an exception is taken to mean @code{BIG_ENDIAN}.
730 Examples of values for @env{GFORTRAN_CONVERT_UNIT} are:
732 @item @code{'big_endian'} Do all unformatted I/O in big_endian mode.
733 @item @code{'little_endian;native:10-20,25'} Do all unformatted I/O
734 in little_endian mode, except for units 10 to 20 and 25, which are in
736 @item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native.
739 Setting the environment variables should be done on the command
740 line or via the @command{export}
741 command for @command{sh}-compatible shells and via @command{setenv}
742 for @command{csh}-compatible shells.
744 Example for @command{sh}:
747 $ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out
750 Example code for @command{csh}:
753 % setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20'
757 Using anything but the native representation for unformatted data
758 carries a significant speed overhead. If speed in this area matters
759 to you, it is best if you use this only for data that needs to be
762 @xref{CONVERT specifier}, for an alternative way to specify the
763 data representation for unformatted files. @xref{Runtime Options}, for
764 setting a default data representation for the whole program. The
765 @code{CONVERT} specifier overrides the @option{-fconvert} compile options.
767 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
768 environment variable will override the CONVERT specifier in the
769 open statement}. This is to give control over data formats to
770 users who do not have the source code of their program available.
772 @node GFORTRAN_ERROR_BACKTRACE
773 @section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors
775 If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to @samp{y},
776 @samp{Y} or @samp{1} (only the first letter is relevant) then a
777 backtrace is printed when a serious run-time error occurs. To disable
778 the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}.
779 Default is to print a backtrace unless the @option{-fno-backtrace}
780 compile option was used.
782 @node GFORTRAN_FORMATTED_BUFFER_SIZE
783 @section @env{GFORTRAN_FORMATTED_BUFFER_SIZE}---Set buffer size for formatted I/O
785 The @env{GFORTRAN_FORMATTED_BUFFER_SIZE} environment variable
786 specifies buffer size in bytes to be used for formatted output.
787 The default value is 8192.
789 @node GFORTRAN_UNFORMATTED_BUFFER_SIZE
790 @section @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE}---Set buffer size for unformatted I/O
792 The @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE} environment variable
793 specifies buffer size in bytes to be used for unformatted output.
794 The default value is 131072.
796 @c =====================================================================
797 @c PART II: LANGUAGE REFERENCE
798 @c =====================================================================
801 \part{II}{Language Reference}
804 @c ---------------------------------------------------------------------
805 @c Fortran standards status
806 @c ---------------------------------------------------------------------
808 @node Fortran standards status
809 @chapter Fortran standards status
812 * Fortran 2003 status::
813 * Fortran 2008 status::
814 * Fortran 2018 status::
817 @node Fortran 2003 status
818 @section Fortran 2003 status
820 GNU Fortran supports several Fortran 2003 features; an incomplete
821 list can be found below. See also the
822 @uref{https://gcc.gnu.org/wiki/Fortran2003, wiki page} about Fortran 2003.
825 @item Procedure pointers including procedure-pointer components with
826 @code{PASS} attribute.
828 @item Procedures which are bound to a derived type (type-bound procedures)
829 including @code{PASS}, @code{PROCEDURE} and @code{GENERIC}, and
830 operators bound to a type.
832 @item Abstract interfaces and type extension with the possibility to
833 override type-bound procedures or to have deferred binding.
835 @item Polymorphic entities (``@code{CLASS}'') for derived types and unlimited
836 polymorphism (``@code{CLASS(*)}'') -- including @code{SAME_TYPE_AS},
837 @code{EXTENDS_TYPE_OF} and @code{SELECT TYPE} for scalars and arrays and
840 @item Generic interface names, which have the same name as derived types,
841 are now supported. This allows one to write constructor functions. Note
842 that Fortran does not support static constructor functions. For static
843 variables, only default initialization or structure-constructor
844 initialization are available.
846 @item The @code{ASSOCIATE} construct.
848 @item Interoperability with C including enumerations,
850 @item In structure constructors the components with default values may be
853 @item Extensions to the @code{ALLOCATE} statement, allowing for a
854 type-specification with type parameter and for allocation and initialization
855 from a @code{SOURCE=} expression; @code{ALLOCATE} and @code{DEALLOCATE}
856 optionally return an error message string via @code{ERRMSG=}.
858 @item Reallocation on assignment: If an intrinsic assignment is
859 used, an allocatable variable on the left-hand side is automatically allocated
860 (if unallocated) or reallocated (if the shape is different). Currently, scalar
861 deferred character length left-hand sides are correctly handled but arrays
862 are not yet fully implemented.
864 @item Deferred-length character variables and scalar deferred-length character
865 components of derived types are supported. (Note that array-valued compoents
866 are not yet implemented.)
868 @item Transferring of allocations via @code{MOVE_ALLOC}.
870 @item The @code{PRIVATE} and @code{PUBLIC} attributes may be given individually
871 to derived-type components.
873 @item In pointer assignments, the lower bound may be specified and
874 the remapping of elements is supported.
876 @item For pointers an @code{INTENT} may be specified which affect the
877 association status not the value of the pointer target.
879 @item Intrinsics @code{command_argument_count}, @code{get_command},
880 @code{get_command_argument}, and @code{get_environment_variable}.
882 @item Support for Unicode characters (ISO 10646) and UTF-8, including
883 the @code{SELECTED_CHAR_KIND} and @code{NEW_LINE} intrinsic functions.
885 @item Support for binary, octal and hexadecimal (BOZ) constants in the
886 intrinsic functions @code{INT}, @code{REAL}, @code{CMPLX} and @code{DBLE}.
888 @item Support for namelist variables with allocatable and pointer
889 attribute and nonconstant length type parameter.
892 @cindex array, constructors
894 Array constructors using square brackets. That is, @code{[...]} rather
895 than @code{(/.../)}. Type-specification for array constructors like
896 @code{(/ some-type :: ... /)}.
898 @item Extensions to the specification and initialization expressions,
899 including the support for intrinsics with real and complex arguments.
901 @item Support for the asynchronous input/output.
904 @cindex @code{FLUSH} statement
905 @cindex statement, @code{FLUSH}
906 @code{FLUSH} statement.
909 @cindex @code{IOMSG=} specifier
910 @code{IOMSG=} specifier for I/O statements.
913 @cindex @code{ENUM} statement
914 @cindex @code{ENUMERATOR} statement
915 @cindex statement, @code{ENUM}
916 @cindex statement, @code{ENUMERATOR}
917 @opindex @code{fshort-enums}
918 Support for the declaration of enumeration constants via the
919 @code{ENUM} and @code{ENUMERATOR} statements. Interoperability with
920 @command{gcc} is guaranteed also for the case where the
921 @command{-fshort-enums} command line option is given.
928 @cindex @code{ALLOCATABLE} dummy arguments
929 @code{ALLOCATABLE} dummy arguments.
931 @cindex @code{ALLOCATABLE} function results
932 @code{ALLOCATABLE} function results
934 @cindex @code{ALLOCATABLE} components of derived types
935 @code{ALLOCATABLE} components of derived types
939 @cindex @code{STREAM} I/O
940 @cindex @code{ACCESS='STREAM'} I/O
941 The @code{OPEN} statement supports the @code{ACCESS='STREAM'} specifier,
942 allowing I/O without any record structure.
945 Namelist input/output for internal files.
947 @item Minor I/O features: Rounding during formatted output, using of
948 a decimal comma instead of a decimal point, setting whether a plus sign
949 should appear for positive numbers. On systems where @code{strtod} honours
950 the rounding mode, the rounding mode is also supported for input.
953 @cindex @code{PROTECTED} statement
954 @cindex statement, @code{PROTECTED}
955 The @code{PROTECTED} statement and attribute.
958 @cindex @code{VALUE} statement
959 @cindex statement, @code{VALUE}
960 The @code{VALUE} statement and attribute.
963 @cindex @code{VOLATILE} statement
964 @cindex statement, @code{VOLATILE}
965 The @code{VOLATILE} statement and attribute.
968 @cindex @code{IMPORT} statement
969 @cindex statement, @code{IMPORT}
970 The @code{IMPORT} statement, allowing to import
971 host-associated derived types.
973 @item The intrinsic modules @code{ISO_FORTRAN_ENVIRONMENT} is supported,
974 which contains parameters of the I/O units, storage sizes. Additionally,
975 procedures for C interoperability are available in the @code{ISO_C_BINDING}
979 @cindex @code{USE, INTRINSIC} statement
980 @cindex statement, @code{USE, INTRINSIC}
981 @cindex @code{ISO_FORTRAN_ENV} statement
982 @cindex statement, @code{ISO_FORTRAN_ENV}
983 @code{USE} statement with @code{INTRINSIC} and @code{NON_INTRINSIC}
984 attribute; supported intrinsic modules: @code{ISO_FORTRAN_ENV},
985 @code{ISO_C_BINDING}, @code{OMP_LIB} and @code{OMP_LIB_KINDS},
989 Renaming of operators in the @code{USE} statement.
994 @node Fortran 2008 status
995 @section Fortran 2008 status
997 The latest version of the Fortran standard is ISO/IEC 1539-1:2010, informally
998 known as Fortran 2008. The official version is available from International
999 Organization for Standardization (ISO) or its national member organizations.
1000 The the final draft (FDIS) can be downloaded free of charge from
1001 @url{http://www.nag.co.uk/@/sc22wg5/@/links.html}. Fortran is developed by the
1002 Working Group 5 of Sub-Committee 22 of the Joint Technical Committee 1 of the
1003 International Organization for Standardization and the International
1004 Electrotechnical Commission (IEC). This group is known as
1005 @uref{http://www.nag.co.uk/sc22wg5/, WG5}.
1007 The GNU Fortran compiler supports several of the new features of Fortran 2008;
1008 the @uref{https://gcc.gnu.org/wiki/Fortran2008Status, wiki} has some information
1009 about the current Fortran 2008 implementation status. In particular, the
1010 following is implemented.
1013 @item The @option{-std=f2008} option and support for the file extensions
1014 @file{.f08} and @file{.F08}.
1016 @item The @code{OPEN} statement now supports the @code{NEWUNIT=} option,
1017 which returns a unique file unit, thus preventing inadvertent use of the
1018 same unit in different parts of the program.
1020 @item The @code{g0} format descriptor and unlimited format items.
1022 @item The mathematical intrinsics @code{ASINH}, @code{ACOSH}, @code{ATANH},
1023 @code{ERF}, @code{ERFC}, @code{GAMMA}, @code{LOG_GAMMA}, @code{BESSEL_J0},
1024 @code{BESSEL_J1}, @code{BESSEL_JN}, @code{BESSEL_Y0}, @code{BESSEL_Y1},
1025 @code{BESSEL_YN}, @code{HYPOT}, @code{NORM2}, and @code{ERFC_SCALED}.
1027 @item Using complex arguments with @code{TAN}, @code{SINH}, @code{COSH},
1028 @code{TANH}, @code{ASIN}, @code{ACOS}, and @code{ATAN} is now possible;
1029 @code{ATAN}(@var{Y},@var{X}) is now an alias for @code{ATAN2}(@var{Y},@var{X}).
1031 @item Support of the @code{PARITY} intrinsic functions.
1033 @item The following bit intrinsics: @code{LEADZ} and @code{TRAILZ} for
1034 counting the number of leading and trailing zero bits, @code{POPCNT} and
1035 @code{POPPAR} for counting the number of one bits and returning the parity;
1036 @code{BGE}, @code{BGT}, @code{BLE}, and @code{BLT} for bitwise comparisons;
1037 @code{DSHIFTL} and @code{DSHIFTR} for combined left and right shifts,
1038 @code{MASKL} and @code{MASKR} for simple left and right justified masks,
1039 @code{MERGE_BITS} for a bitwise merge using a mask, @code{SHIFTA},
1040 @code{SHIFTL} and @code{SHIFTR} for shift operations, and the
1041 transformational bit intrinsics @code{IALL}, @code{IANY} and @code{IPARITY}.
1043 @item Support of the @code{EXECUTE_COMMAND_LINE} intrinsic subroutine.
1045 @item Support for the @code{STORAGE_SIZE} intrinsic inquiry function.
1047 @item The @code{INT@{8,16,32@}} and @code{REAL@{32,64,128@}} kind type
1048 parameters and the array-valued named constants @code{INTEGER_KINDS},
1049 @code{LOGICAL_KINDS}, @code{REAL_KINDS} and @code{CHARACTER_KINDS} of
1050 the intrinsic module @code{ISO_FORTRAN_ENV}.
1052 @item The module procedures @code{C_SIZEOF} of the intrinsic module
1053 @code{ISO_C_BINDINGS} and @code{COMPILER_VERSION} and @code{COMPILER_OPTIONS}
1054 of @code{ISO_FORTRAN_ENV}.
1056 @item Coarray support for serial programs with @option{-fcoarray=single} flag
1057 and experimental support for multiple images with the @option{-fcoarray=lib}
1060 @item Submodules are supported. It should noted that @code{MODULEs} do not
1061 produce the smod file needed by the descendent @code{SUBMODULEs} unless they
1062 contain at least one @code{MODULE PROCEDURE} interface. The reason for this is
1063 that @code{SUBMODULEs} are useless without @code{MODULE PROCEDUREs}. See
1064 http://j3-fortran.org/doc/meeting/207/15-209.txt for a discussion and a draft
1065 interpretation. Adopting this interpretation has the advantage that code that
1066 does not use submodules does not generate smod files.
1068 @item The @code{DO CONCURRENT} construct is supported.
1070 @item The @code{BLOCK} construct is supported.
1072 @item The @code{STOP} and the new @code{ERROR STOP} statements now
1073 support all constant expressions. Both show the signals which were signaling
1076 @item Support for the @code{CONTIGUOUS} attribute.
1078 @item Support for @code{ALLOCATE} with @code{MOLD}.
1080 @item Support for the @code{IMPURE} attribute for procedures, which
1081 allows for @code{ELEMENTAL} procedures without the restrictions of
1084 @item Null pointers (including @code{NULL()}) and not-allocated variables
1085 can be used as actual argument to optional non-pointer, non-allocatable
1086 dummy arguments, denoting an absent argument.
1088 @item Non-pointer variables with @code{TARGET} attribute can be used as
1089 actual argument to @code{POINTER} dummies with @code{INTENT(IN)}.
1091 @item Pointers including procedure pointers and those in a derived
1092 type (pointer components) can now be initialized by a target instead
1093 of only by @code{NULL}.
1095 @item The @code{EXIT} statement (with construct-name) can be now be
1096 used to leave not only the @code{DO} but also the @code{ASSOCIATE},
1097 @code{BLOCK}, @code{IF}, @code{SELECT CASE} and @code{SELECT TYPE}
1100 @item Internal procedures can now be used as actual argument.
1102 @item Minor features: obsolesce diagnostics for @code{ENTRY} with
1103 @option{-std=f2008}; a line may start with a semicolon; for internal
1104 and module procedures @code{END} can be used instead of
1105 @code{END SUBROUTINE} and @code{END FUNCTION}; @code{SELECTED_REAL_KIND}
1106 now also takes a @code{RADIX} argument; intrinsic types are supported
1107 for @code{TYPE}(@var{intrinsic-type-spec}); multiple type-bound procedures
1108 can be declared in a single @code{PROCEDURE} statement; implied-shape
1109 arrays are supported for named constants (@code{PARAMETER}).
1114 @node Fortran 2018 status
1115 @section Status of Fortran 2018 support
1118 @item ERROR STOP in a PURE procedure
1119 An @code{ERROR STOP} statement is permitted in a @code{PURE}
1122 @item IMPLICIT NONE with a spec-list
1123 Support the @code{IMPLICIT NONE} statement with an
1124 @code{implicit-none-spec-list}.
1126 @item Behavior of INQUIRE with the RECL= specifier
1128 The behavior of the @code{INQUIRE} statement with the @code{RECL=}
1129 specifier now conforms to Fortran 2018.
1134 @subsection TS 29113 Status (Further Interoperability with C)
1136 GNU Fortran supports some of the new features of the Technical
1137 Specification (TS) 29113 on Further Interoperability of Fortran with C.
1138 The @uref{https://gcc.gnu.org/wiki/TS29113Status, wiki} has some information
1139 about the current TS 29113 implementation status. In particular, the
1140 following is implemented.
1142 See also @ref{Further Interoperability of Fortran with C}.
1145 @item The @code{OPTIONAL} attribute is allowed for dummy arguments
1146 of @code{BIND(C) procedures.}
1148 @item The @code{RANK} intrinsic is supported.
1150 @item GNU Fortran's implementation for variables with @code{ASYNCHRONOUS}
1151 attribute is compatible with TS 29113.
1153 @item Assumed types (@code{TYPE(*)}).
1155 @item Assumed-rank (@code{DIMENSION(..)}).
1157 @item ISO_Fortran_binding (now in Fortran 2018 18.4) is implemented such that
1158 conversion of the array descriptor for assumed type or assumed rank arrays is
1159 done in the library. The include file ISO_Fortran_binding.h is can be found in
1160 @code{~prefix/lib/gcc/$target/$version}.
1165 @subsection TS 18508 Status (Additional Parallel Features)
1167 GNU Fortran supports the following new features of the Technical
1168 Specification 18508 on Additional Parallel Features in Fortran:
1171 @item The new atomic ADD, CAS, FETCH and ADD/OR/XOR, OR and XOR intrinsics.
1173 @item The @code{CO_MIN} and @code{CO_MAX} and @code{SUM} reduction intrinsics.
1174 And the @code{CO_BROADCAST} and @code{CO_REDUCE} intrinsic, except that those
1175 do not support polymorphic types or types with allocatable, pointer or
1176 polymorphic components.
1178 @item Events (@code{EVENT POST}, @code{EVENT WAIT}, @code{EVENT_QUERY})
1180 @item Failed images (@code{FAIL IMAGE}, @code{IMAGE_STATUS},
1181 @code{FAILED_IMAGES}, @code{STOPPED_IMAGES})
1186 @c ---------------------------------------------------------------------
1187 @c Compiler Characteristics
1188 @c ---------------------------------------------------------------------
1190 @node Compiler Characteristics
1191 @chapter Compiler Characteristics
1193 This chapter describes certain characteristics of the GNU Fortran
1194 compiler, that are not specified by the Fortran standard, but which
1195 might in some way or another become visible to the programmer.
1198 * KIND Type Parameters::
1199 * Internal representation of LOGICAL variables::
1200 * Evaluation of logical expressions::
1201 * MAX and MIN intrinsics with REAL NaN arguments::
1202 * Thread-safety of the runtime library::
1203 * Data consistency and durability::
1204 * Files opened without an explicit ACTION= specifier::
1205 * File operations on symbolic links::
1206 * File format of unformatted sequential files::
1207 * Asynchronous I/O::
1211 @node KIND Type Parameters
1212 @section KIND Type Parameters
1215 The @code{KIND} type parameters supported by GNU Fortran for the primitive
1221 1, 2, 4, 8*, 16*, default: 4**
1224 1, 2, 4, 8*, 16*, default: 4**
1227 4, 8, 10*, 16*, default: 4***
1230 4, 8, 10*, 16*, default: 4***
1232 @item DOUBLE PRECISION
1233 4, 8, 10*, 16*, default: 8***
1241 * not available on all systems @*
1242 ** unless @option{-fdefault-integer-8} is used @*
1243 *** unless @option{-fdefault-real-8} is used (see @ref{Fortran Dialect Options})
1246 The @code{KIND} value matches the storage size in bytes, except for
1247 @code{COMPLEX} where the storage size is twice as much (or both real and
1248 imaginary part are a real value of the given size). It is recommended to use
1249 the @ref{SELECTED_CHAR_KIND}, @ref{SELECTED_INT_KIND} and
1250 @ref{SELECTED_REAL_KIND} intrinsics or the @code{INT8}, @code{INT16},
1251 @code{INT32}, @code{INT64}, @code{REAL32}, @code{REAL64}, and @code{REAL128}
1252 parameters of the @code{ISO_FORTRAN_ENV} module instead of the concrete values.
1253 The available kind parameters can be found in the constant arrays
1254 @code{CHARACTER_KINDS}, @code{INTEGER_KINDS}, @code{LOGICAL_KINDS} and
1255 @code{REAL_KINDS} in the @ref{ISO_FORTRAN_ENV} module. For C interoperability,
1256 the kind parameters of the @ref{ISO_C_BINDING} module should be used.
1259 @node Internal representation of LOGICAL variables
1260 @section Internal representation of LOGICAL variables
1261 @cindex logical, variable representation
1263 The Fortran standard does not specify how variables of @code{LOGICAL}
1264 type are represented, beyond requiring that @code{LOGICAL} variables
1265 of default kind have the same storage size as default @code{INTEGER}
1266 and @code{REAL} variables. The GNU Fortran internal representation is
1269 A @code{LOGICAL(KIND=N)} variable is represented as an
1270 @code{INTEGER(KIND=N)} variable, however, with only two permissible
1271 values: @code{1} for @code{.TRUE.} and @code{0} for
1272 @code{.FALSE.}. Any other integer value results in undefined behavior.
1274 See also @ref{Argument passing conventions} and @ref{Interoperability with C}.
1277 @node Evaluation of logical expressions
1278 @section Evaluation of logical expressions
1280 The Fortran standard does not require the compiler to evaluate all parts of an
1281 expression, if they do not contribute to the final result. For logical
1282 expressions with @code{.AND.} or @code{.OR.} operators, in particular, GNU
1283 Fortran will optimize out function calls (even to impure functions) if the
1284 result of the expression can be established without them. However, since not
1285 all compilers do that, and such an optimization can potentially modify the
1286 program flow and subsequent results, GNU Fortran throws warnings for such
1287 situations with the @option{-Wfunction-elimination} flag.
1290 @node MAX and MIN intrinsics with REAL NaN arguments
1291 @section MAX and MIN intrinsics with REAL NaN arguments
1292 @cindex MAX, MIN, NaN
1294 The Fortran standard does not specify what the result of the
1295 @code{MAX} and @code{MIN} intrinsics are if one of the arguments is a
1296 @code{NaN}. Accordingly, the GNU Fortran compiler does not specify
1297 that either, as this allows for faster and more compact code to be
1298 generated. If the programmer wishes to take some specific action in
1299 case one of the arguments is a @code{NaN}, it is necessary to
1300 explicitly test the arguments before calling @code{MAX} or @code{MIN},
1301 e.g. with the @code{IEEE_IS_NAN} function from the intrinsic module
1302 @code{IEEE_ARITHMETIC}.
1305 @node Thread-safety of the runtime library
1306 @section Thread-safety of the runtime library
1307 @cindex thread-safety, threads
1309 GNU Fortran can be used in programs with multiple threads, e.g.@: by
1310 using OpenMP, by calling OS thread handling functions via the
1311 @code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code
1312 being called from a multi-threaded program.
1314 The GNU Fortran runtime library, (@code{libgfortran}), supports being
1315 called concurrently from multiple threads with the following
1318 During library initialization, the C @code{getenv} function is used,
1319 which need not be thread-safe. Similarly, the @code{getenv}
1320 function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and
1321 @code{GETENV} intrinsics. It is the responsibility of the user to
1322 ensure that the environment is not being updated concurrently when any
1323 of these actions are taking place.
1325 The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are
1326 implemented with the @code{system} function, which need not be
1327 thread-safe. It is the responsibility of the user to ensure that
1328 @code{system} is not called concurrently.
1330 For platforms not supporting thread-safe POSIX functions, further
1331 functionality might not be thread-safe. For details, please consult
1332 the documentation for your operating system.
1334 The GNU Fortran runtime library uses various C library functions that
1335 depend on the locale, such as @code{strtod} and @code{snprintf}. In
1336 order to work correctly in locale-aware programs that set the locale
1337 using @code{setlocale}, the locale is reset to the default ``C''
1338 locale while executing a formatted @code{READ} or @code{WRITE}
1339 statement. On targets supporting the POSIX 2008 per-thread locale
1340 functions (e.g. @code{newlocale}, @code{uselocale},
1341 @code{freelocale}), these are used and thus the global locale set
1342 using @code{setlocale} or the per-thread locales in other threads are
1343 not affected. However, on targets lacking this functionality, the
1344 global LC_NUMERIC locale is set to ``C'' during the formatted I/O.
1345 Thus, on such targets it's not safe to call @code{setlocale}
1346 concurrently from another thread while a Fortran formatted I/O
1347 operation is in progress. Also, other threads doing something
1348 dependent on the LC_NUMERIC locale might not work correctly if a
1349 formatted I/O operation is in progress in another thread.
1351 @node Data consistency and durability
1352 @section Data consistency and durability
1353 @cindex consistency, durability
1355 This section contains a brief overview of data and metadata
1356 consistency and durability issues when doing I/O.
1358 With respect to durability, GNU Fortran makes no effort to ensure that
1359 data is committed to stable storage. If this is required, the GNU
1360 Fortran programmer can use the intrinsic @code{FNUM} to retrieve the
1361 low level file descriptor corresponding to an open Fortran unit. Then,
1362 using e.g. the @code{ISO_C_BINDING} feature, one can call the
1363 underlying system call to flush dirty data to stable storage, such as
1364 @code{fsync} on POSIX, @code{_commit} on MingW, or @code{fcntl(fd,
1365 F_FULLSYNC, 0)} on Mac OS X. The following example shows how to call
1369 ! Declare the interface for POSIX fsync function
1371 function fsync (fd) bind(c,name="fsync")
1372 use iso_c_binding, only: c_int
1373 integer(c_int), value :: fd
1374 integer(c_int) :: fsync
1378 ! Variable declaration
1382 open (10,file="foo")
1385 ! Perform I/O on unit 10
1390 ret = fsync(fnum(10))
1392 ! Handle possible error
1393 if (ret /= 0) stop "Error calling FSYNC"
1396 With respect to consistency, for regular files GNU Fortran uses
1397 buffered I/O in order to improve performance. This buffer is flushed
1398 automatically when full and in some other situations, e.g. when
1399 closing a unit. It can also be explicitly flushed with the
1400 @code{FLUSH} statement. Also, the buffering can be turned off with the
1401 @code{GFORTRAN_UNBUFFERED_ALL} and
1402 @code{GFORTRAN_UNBUFFERED_PRECONNECTED} environment variables. Special
1403 files, such as terminals and pipes, are always unbuffered. Sometimes,
1404 however, further things may need to be done in order to allow other
1405 processes to see data that GNU Fortran has written, as follows.
1407 The Windows platform supports a relaxed metadata consistency model,
1408 where file metadata is written to the directory lazily. This means
1409 that, for instance, the @code{dir} command can show a stale size for a
1410 file. One can force a directory metadata update by closing the unit,
1411 or by calling @code{_commit} on the file descriptor. Note, though,
1412 that @code{_commit} will force all dirty data to stable storage, which
1413 is often a very slow operation.
1415 The Network File System (NFS) implements a relaxed consistency model
1416 called open-to-close consistency. Closing a file forces dirty data and
1417 metadata to be flushed to the server, and opening a file forces the
1418 client to contact the server in order to revalidate cached
1419 data. @code{fsync} will also force a flush of dirty data and metadata
1420 to the server. Similar to @code{open} and @code{close}, acquiring and
1421 releasing @code{fcntl} file locks, if the server supports them, will
1422 also force cache validation and flushing dirty data and metadata.
1425 @node Files opened without an explicit ACTION= specifier
1426 @section Files opened without an explicit ACTION= specifier
1427 @cindex open, action
1429 The Fortran standard says that if an @code{OPEN} statement is executed
1430 without an explicit @code{ACTION=} specifier, the default value is
1431 processor dependent. GNU Fortran behaves as follows:
1434 @item Attempt to open the file with @code{ACTION='READWRITE'}
1435 @item If that fails, try to open with @code{ACTION='READ'}
1436 @item If that fails, try to open with @code{ACTION='WRITE'}
1437 @item If that fails, generate an error
1441 @node File operations on symbolic links
1442 @section File operations on symbolic links
1443 @cindex file, symbolic link
1445 This section documents the behavior of GNU Fortran for file operations on
1446 symbolic links, on systems that support them.
1450 @item Results of INQUIRE statements of the ``inquire by file'' form will
1451 relate to the target of the symbolic link. For example,
1452 @code{INQUIRE(FILE="foo",EXIST=ex)} will set @var{ex} to @var{.true.} if
1453 @var{foo} is a symbolic link pointing to an existing file, and @var{.false.}
1454 if @var{foo} points to an non-existing file (``dangling'' symbolic link).
1456 @item Using the @code{OPEN} statement with a @code{STATUS="NEW"} specifier
1457 on a symbolic link will result in an error condition, whether the symbolic
1458 link points to an existing target or is dangling.
1460 @item If a symbolic link was connected, using the @code{CLOSE} statement
1461 with a @code{STATUS="DELETE"} specifier will cause the symbolic link itself
1462 to be deleted, not its target.
1466 @node File format of unformatted sequential files
1467 @section File format of unformatted sequential files
1468 @cindex file, unformatted sequential
1469 @cindex unformatted sequential
1470 @cindex sequential, unformatted
1471 @cindex record marker
1474 Unformatted sequential files are stored as logical records using
1475 record markers. Each logical record consists of one of more
1478 Each subrecord consists of a leading record marker, the data written
1479 by the user program, and a trailing record marker. The record markers
1480 are four-byte integers by default, and eight-byte integers if the
1481 @option{-fmax-subrecord-length=8} option (which exists for backwards
1482 compability only) is in effect.
1484 The representation of the record markers is that of unformatted files
1485 given with the @option{-fconvert} option, the @ref{CONVERT specifier}
1486 in an open statement or the @ref{GFORTRAN_CONVERT_UNIT} environment
1489 The maximum number of bytes of user data in a subrecord is 2147483639
1490 (2 GiB - 9) for a four-byte record marker. This limit can be lowered
1491 with the @option{-fmax-subrecord-length} option, altough this is
1492 rarely useful. If the length of a logical record exceeds this limit,
1493 the data is distributed among several subrecords.
1495 The absolute of the number stored in the record markers is the number
1496 of bytes of user data in the corresponding subrecord. If the leading
1497 record marker of a subrecord contains a negative number, another
1498 subrecord follows the current one. If the trailing record marker
1499 contains a negative number, then there is a preceding subrecord.
1501 In the most simple case, with only one subrecord per logical record,
1502 both record markers contain the number of bytes of user data in the
1505 The format for unformatted sequential data can be duplicated using
1506 unformatted stream, as shown in the example program for an unformatted
1507 record containing a single subrecord:
1511 use iso_fortran_env, only: int32
1514 real, dimension(10) :: a, b
1515 call random_number(a)
1516 open (10,file='test.dat',form='unformatted',access='stream')
1517 inquire (iolength=i) a
1520 open (10,file='test.dat',form='unformatted')
1522 if (all (a == b)) print *,'success!'
1526 @node Asynchronous I/O
1527 @section Asynchronous I/O
1528 @cindex input/output, asynchronous
1529 @cindex asynchronous I/O
1531 Asynchronous I/O is supported if the program is linked against the
1532 POSIX thread library. If that is not the case, all I/O is performed
1533 as synchronous. On systems which do not support pthread condition
1534 variables, such as AIX, I/O is also performed as synchronous.
1536 On some systems, such as Darwin or Solaris, the POSIX thread library
1537 is always linked in, so asynchronous I/O is always performed. On other
1538 sytems, such as Linux, it is necessary to specify @option{-pthread},
1539 @option{-lpthread} or @option{-fopenmp} during the linking step.
1541 @c ---------------------------------------------------------------------
1543 @c ---------------------------------------------------------------------
1545 @c Maybe this chapter should be merged with the 'Standards' section,
1546 @c whenever that is written :-)
1552 The two sections below detail the extensions to standard Fortran that are
1553 implemented in GNU Fortran, as well as some of the popular or
1554 historically important extensions that are not (or not yet) implemented.
1555 For the latter case, we explain the alternatives available to GNU Fortran
1556 users, including replacement by standard-conforming code or GNU
1560 * Extensions implemented in GNU Fortran::
1561 * Extensions not implemented in GNU Fortran::
1565 @node Extensions implemented in GNU Fortran
1566 @section Extensions implemented in GNU Fortran
1567 @cindex extensions, implemented
1569 GNU Fortran implements a number of extensions over standard Fortran.
1570 This chapter contains information on their syntax and meaning. There
1571 are currently two categories of GNU Fortran extensions, those that
1572 provide functionality beyond that provided by any standard, and those
1573 that are supported by GNU Fortran purely for backward compatibility
1574 with legacy compilers. By default, @option{-std=gnu} allows the
1575 compiler to accept both types of extensions, but to warn about the use
1576 of the latter. Specifying either @option{-std=f95},
1577 @option{-std=f2003}, @option{-std=f2008}, or @option{-std=f2018}
1578 disables both types of extensions, and @option{-std=legacy} allows
1579 both without warning. The special compile flag @option{-fdec} enables
1580 additional compatibility extensions along with those enabled by
1581 @option{-std=legacy}.
1584 * Old-style kind specifications::
1585 * Old-style variable initialization::
1586 * Extensions to namelist::
1587 * X format descriptor without count field::
1588 * Commas in FORMAT specifications::
1589 * Missing period in FORMAT specifications::
1590 * Default widths for F@comma{} G and I format descriptors::
1592 * @code{Q} exponent-letter::
1593 * BOZ literal constants::
1594 * Real array indices::
1596 * Implicitly convert LOGICAL and INTEGER values::
1597 * Hollerith constants support::
1598 * Character conversion::
1600 * CONVERT specifier::
1603 * Argument list functions::
1604 * Read/Write after EOF marker::
1605 * STRUCTURE and RECORD::
1607 * Type variants for integer intrinsics::
1608 * AUTOMATIC and STATIC attributes::
1609 * Extended math intrinsics::
1610 * Form feed as whitespace::
1611 * TYPE as an alias for PRINT::
1612 * %LOC as an rvalue::
1614 * Bitwise logical operators::
1615 * Extended I/O specifiers::
1616 * Legacy PARAMETER statements::
1617 * Default exponents::
1620 @node Old-style kind specifications
1621 @subsection Old-style kind specifications
1622 @cindex kind, old-style
1624 GNU Fortran allows old-style kind specifications in declarations. These
1630 where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
1631 etc.), and where @code{size} is a byte count corresponding to the
1632 storage size of a valid kind for that type. (For @code{COMPLEX}
1633 variables, @code{size} is the total size of the real and imaginary
1634 parts.) The statement then declares @code{x}, @code{y} and @code{z} to
1635 be of type @code{TYPESPEC} with the appropriate kind. This is
1636 equivalent to the standard-conforming declaration
1641 where @code{k} is the kind parameter suitable for the intended precision. As
1642 kind parameters are implementation-dependent, use the @code{KIND},
1643 @code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve
1644 the correct value, for instance @code{REAL*8 x} can be replaced by:
1646 INTEGER, PARAMETER :: dbl = KIND(1.0d0)
1650 @node Old-style variable initialization
1651 @subsection Old-style variable initialization
1653 GNU Fortran allows old-style initialization of variables of the
1657 REAL x(2,2) /3*0.,1./
1659 The syntax for the initializers is as for the @code{DATA} statement, but
1660 unlike in a @code{DATA} statement, an initializer only applies to the
1661 variable immediately preceding the initialization. In other words,
1662 something like @code{INTEGER I,J/2,3/} is not valid. This style of
1663 initialization is only allowed in declarations without double colons
1664 (@code{::}); the double colons were introduced in Fortran 90, which also
1665 introduced a standard syntax for initializing variables in type
1668 Examples of standard-conforming code equivalent to the above example
1672 INTEGER :: i = 1, j = 2
1673 REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
1677 DATA i/1/, j/2/, x/3*0.,1./
1680 Note that variables which are explicitly initialized in declarations
1681 or in @code{DATA} statements automatically acquire the @code{SAVE}
1684 @node Extensions to namelist
1685 @subsection Extensions to namelist
1688 GNU Fortran fully supports the Fortran 95 standard for namelist I/O
1689 including array qualifiers, substrings and fully qualified derived types.
1690 The output from a namelist write is compatible with namelist read. The
1691 output has all names in upper case and indentation to column 1 after the
1692 namelist name. Two extensions are permitted:
1694 Old-style use of @samp{$} instead of @samp{&}
1697 X(:)%Y(2) = 1.0 2.0 3.0
1702 It should be noted that the default terminator is @samp{/} rather than
1705 Querying of the namelist when inputting from stdin. After at least
1706 one space, entering @samp{?} sends to stdout the namelist name and the names of
1707 the variables in the namelist:
1718 Entering @samp{=?} outputs the namelist to stdout, as if
1719 @code{WRITE(*,NML = mynml)} had been called:
1724 X(1)%Y= 0.000000 , 1.000000 , 0.000000 ,
1725 X(2)%Y= 0.000000 , 2.000000 , 0.000000 ,
1726 X(3)%Y= 0.000000 , 3.000000 , 0.000000 ,
1730 To aid this dialog, when input is from stdin, errors send their
1731 messages to stderr and execution continues, even if @code{IOSTAT} is set.
1733 @code{PRINT} namelist is permitted. This causes an error if
1734 @option{-std=f95} is used.
1737 REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/)
1740 END PROGRAM test_print
1743 Expanded namelist reads are permitted. This causes an error if
1744 @option{-std=f95} is used. In the following example, the first element
1745 of the array will be given the value 0.00 and the two succeeding
1746 elements will be given the values 1.00 and 2.00.
1749 X(1,1) = 0.00 , 1.00 , 2.00
1753 When writing a namelist, if no @code{DELIM=} is specified, by default a
1754 double quote is used to delimit character strings. If -std=F95, F2003,
1755 or F2008, etc, the delim status is set to 'none'. Defaulting to
1756 quotes ensures that namelists with character strings can be subsequently
1757 read back in accurately.
1759 @node X format descriptor without count field
1760 @subsection @code{X} format descriptor without count field
1762 To support legacy codes, GNU Fortran permits the count field of the
1763 @code{X} edit descriptor in @code{FORMAT} statements to be omitted.
1764 When omitted, the count is implicitly assumed to be one.
1768 10 FORMAT (I1, X, I1)
1771 @node Commas in FORMAT specifications
1772 @subsection Commas in @code{FORMAT} specifications
1774 To support legacy codes, GNU Fortran allows the comma separator
1775 to be omitted immediately before and after character string edit
1776 descriptors in @code{FORMAT} statements. A comma with no following format
1777 decriptor is permited if the @option{-fdec-blank-format-item} is given on
1778 the command line. This is considered non-conforming code and is
1783 10 FORMAT ('FOO='I1' BAR='I2)
1789 @node Missing period in FORMAT specifications
1790 @subsection Missing period in @code{FORMAT} specifications
1792 To support legacy codes, GNU Fortran allows missing periods in format
1793 specifications if and only if @option{-std=legacy} is given on the
1794 command line. This is considered non-conforming code and is
1803 @node Default widths for F@comma{} G and I format descriptors
1804 @subsection Default widths for @code{F}, @code{G} and @code{I} format descriptors
1806 To support legacy codes, GNU Fortran allows width to be omitted from format
1807 specifications if and only if @option{-fdec-format-defaults} is given on the
1808 command line. Default widths will be used. This is considered non-conforming
1809 code and is discouraged.
1814 WRITE(*,10) value1, value1, value2
1815 10 FORMAT ('F, G, I')
1819 @node I/O item lists
1820 @subsection I/O item lists
1821 @cindex I/O item lists
1823 To support legacy codes, GNU Fortran allows the input item list
1824 of the @code{READ} statement, and the output item lists of the
1825 @code{WRITE} and @code{PRINT} statements, to start with a comma.
1827 @node @code{Q} exponent-letter
1828 @subsection @code{Q} exponent-letter
1829 @cindex @code{Q} exponent-letter
1831 GNU Fortran accepts real literal constants with an exponent-letter
1832 of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted
1833 as a @code{REAL(16)} entity on targets that support this type. If
1834 the target does not support @code{REAL(16)} but has a @code{REAL(10)}
1835 type, then the real-literal-constant will be interpreted as a
1836 @code{REAL(10)} entity. In the absence of @code{REAL(16)} and
1837 @code{REAL(10)}, an error will occur.
1839 @node BOZ literal constants
1840 @subsection BOZ literal constants
1841 @cindex BOZ literal constants
1843 Besides decimal constants, Fortran also supports binary (@code{b}),
1844 octal (@code{o}) and hexadecimal (@code{z}) integer constants. The
1845 syntax is: @samp{prefix quote digits quote}, were the prefix is
1846 either @code{b}, @code{o} or @code{z}, quote is either @code{'} or
1847 @code{"} and the digits are @code{0} or @code{1} for binary,
1848 between @code{0} and @code{7} for octal, and between @code{0} and
1849 @code{F} for hexadecimal. (Example: @code{b'01011101'}.)
1851 Up to Fortran 95, BOZ literal constants were only allowed to initialize
1852 integer variables in DATA statements. Since Fortran 2003 BOZ literal
1853 constants are also allowed as actual arguments to the @code{REAL},
1854 @code{DBLE}, @code{INT} and @code{CMPLX} intrinsic functions.
1855 The BOZ literal constant is simply a string of bits, which is padded
1856 or truncated as needed, during conversion to a numeric type. The
1857 Fortran standard states that the treatment of the sign bit is processor
1858 dependent. Gfortran interprets the sign bit as a user would expect.
1860 As a deprecated extension, GNU Fortran allows hexadecimal BOZ literal
1861 constants to be specified using the @code{X} prefix. That the BOZ literal
1862 constant can also be specified by adding a suffix to the string, for
1863 example, @code{Z'ABC'} and @code{'ABC'X} are equivalent. Additionally,
1864 as extension, BOZ literals are permitted in some contexts outside of
1865 @code{DATA} and the intrinsic functions listed in the Fortran standard.
1866 Use @option{-fallow-invalid-boz} to enable the extension.
1868 @node Real array indices
1869 @subsection Real array indices
1870 @cindex array, indices of type real
1872 As an extension, GNU Fortran allows the use of @code{REAL} expressions
1873 or variables as array indices.
1875 @node Unary operators
1876 @subsection Unary operators
1877 @cindex operators, unary
1879 As an extension, GNU Fortran allows unary plus and unary minus operators
1880 to appear as the second operand of binary arithmetic operators without
1881 the need for parenthesis.
1887 @node Implicitly convert LOGICAL and INTEGER values
1888 @subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values
1889 @cindex conversion, to integer
1890 @cindex conversion, to logical
1892 As an extension for backwards compatibility with other compilers, GNU
1893 Fortran allows the implicit conversion of @code{LOGICAL} values to
1894 @code{INTEGER} values and vice versa. When converting from a
1895 @code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as
1896 zero, and @code{.TRUE.} is interpreted as one. When converting from
1897 @code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as
1898 @code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}.
1909 However, there is no implicit conversion of @code{INTEGER} values in
1910 @code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values
1913 @node Hollerith constants support
1914 @subsection Hollerith constants support
1915 @cindex Hollerith constants
1917 GNU Fortran supports Hollerith constants in assignments, @code{DATA}
1918 statements, function and subroutine arguments. A Hollerith constant is
1919 written as a string of characters preceded by an integer constant
1920 indicating the character count, and the letter @code{H} or
1921 @code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER},
1922 @code{REAL}, or @code{COMPLEX}), @code{LOGICAL} or @code{CHARACTER} variable.
1923 The constant will be padded with spaces or truncated to fit the size of
1924 the variable in which it is stored.
1926 Examples of valid uses of Hollerith constants:
1929 data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/
1930 x(1) = 16HABCDEFGHIJKLMNOP
1934 Examples of Hollerith constants:
1937 a = 0H ! Invalid, at least one character is needed.
1939 a = 8H12345678 ! Valid, but the Hollerith constant will be truncated.
1940 a = 3Hxyz ! Valid, but the Hollerith constant will be padded.
1943 In general, Hollerith constants were used to provide a rudimentary
1944 facility for handling character strings in early Fortran compilers,
1945 prior to the introduction of @code{CHARACTER} variables in Fortran 77;
1946 in those cases, the standard-compliant equivalent is to convert the
1947 program to use proper character strings. On occasion, there may be a
1948 case where the intent is specifically to initialize a numeric variable
1949 with a given byte sequence. In these cases, the same result can be
1950 obtained by using the @code{TRANSFER} statement, as in this example.
1952 integer(kind=4) :: a
1953 a = transfer ("abcd", a) ! equivalent to: a = 4Habcd
1956 The use of the @option{-fdec} option extends support of Hollerith constants
1961 if (a .ne. 4habcd) then
1962 write(*,*) "no match"
1966 Supported types are numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}),
1967 and @code{CHARACTER}.
1969 @node Character conversion
1970 @subsection Character conversion
1971 @cindex conversion, to character
1973 Allowing character literals to be used in a similar way to Hollerith constants
1974 is a non-standard extension. This feature is enabled using
1975 -fdec-char-conversions and only applies to character literals of @code{kind=1}.
1977 Character literals can be used in @code{DATA} statements and assignments with
1978 numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}) or @code{LOGICAL}
1979 variables. Like Hollerith constants they are copied byte-wise fashion. The
1980 constant will be padded with spaces or truncated to fit the size of the
1981 variable in which it is stored.
1988 x = 'A' ! Will be padded.
1989 x = 'ab1234' ! Will be truncated.
1994 @subsection Cray pointers
1995 @cindex pointer, Cray
1997 Cray pointers are part of a non-standard extension that provides a
1998 C-like pointer in Fortran. This is accomplished through a pair of
1999 variables: an integer "pointer" that holds a memory address, and a
2000 "pointee" that is used to dereference the pointer.
2002 Pointer/pointee pairs are declared in statements of the form:
2004 pointer ( <pointer> , <pointee> )
2008 pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ...
2010 The pointer is an integer that is intended to hold a memory address.
2011 The pointee may be an array or scalar.
2012 If an assumed-size array is permitted within the scoping unit, a
2013 pointee can be an assumed-size array.
2014 That is, the last dimension may be left unspecified by using a @code{*}
2015 in place of a value. A pointee cannot be an assumed shape array.
2016 No space is allocated for the pointee.
2018 The pointee may have its type declared before or after the pointer
2019 statement, and its array specification (if any) may be declared
2020 before, during, or after the pointer statement. The pointer may be
2021 declared as an integer prior to the pointer statement. However, some
2022 machines have default integer sizes that are different than the size
2023 of a pointer, and so the following code is not portable:
2028 If a pointer is declared with a kind that is too small, the compiler
2029 will issue a warning; the resulting binary will probably not work
2030 correctly, because the memory addresses stored in the pointers may be
2031 truncated. It is safer to omit the first line of the above example;
2032 if explicit declaration of ipt's type is omitted, then the compiler
2033 will ensure that ipt is an integer variable large enough to hold a
2036 Pointer arithmetic is valid with Cray pointers, but it is not the same
2037 as C pointer arithmetic. Cray pointers are just ordinary integers, so
2038 the user is responsible for determining how many bytes to add to a
2039 pointer in order to increment it. Consider the following example:
2043 pointer (ipt, pointee)
2047 The last statement does not set @code{ipt} to the address of
2048 @code{target(1)}, as it would in C pointer arithmetic. Adding @code{1}
2049 to @code{ipt} just adds one byte to the address stored in @code{ipt}.
2051 Any expression involving the pointee will be translated to use the
2052 value stored in the pointer as the base address.
2054 To get the address of elements, this extension provides an intrinsic
2055 function @code{LOC()}. The @code{LOC()} function is equivalent to the
2056 @code{&} operator in C, except the address is cast to an integer type:
2059 pointer(ipt, arpte(10))
2061 ipt = loc(ar) ! Makes arpte is an alias for ar
2062 arpte(1) = 1.0 ! Sets ar(1) to 1.0
2064 The pointer can also be set by a call to the @code{MALLOC} intrinsic
2067 Cray pointees often are used to alias an existing variable. For
2075 As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for
2076 @code{target}. The optimizer, however, will not detect this aliasing, so
2077 it is unsafe to use @code{iarr} and @code{target} simultaneously. Using
2078 a pointee in any way that violates the Fortran aliasing rules or
2079 assumptions is illegal. It is the user's responsibility to avoid doing
2080 this; the compiler works under the assumption that no such aliasing
2083 Cray pointers will work correctly when there is no aliasing (i.e., when
2084 they are used to access a dynamically allocated block of memory), and
2085 also in any routine where a pointee is used, but any variable with which
2086 it shares storage is not used. Code that violates these rules may not
2087 run as the user intends. This is not a bug in the optimizer; any code
2088 that violates the aliasing rules is illegal. (Note that this is not
2089 unique to GNU Fortran; any Fortran compiler that supports Cray pointers
2090 will ``incorrectly'' optimize code with illegal aliasing.)
2092 There are a number of restrictions on the attributes that can be applied
2093 to Cray pointers and pointees. Pointees may not have the
2094 @code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY},
2095 @code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers
2096 may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET},
2097 @code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor
2098 may they be function results. Pointees may not occur in more than one
2099 pointer statement. A pointee cannot be a pointer. Pointees cannot occur
2100 in equivalence, common, or data statements.
2102 A Cray pointer may also point to a function or a subroutine. For
2103 example, the following excerpt is valid:
2107 pointer (subptr,subpte)
2117 A pointer may be modified during the course of a program, and this
2118 will change the location to which the pointee refers. However, when
2119 pointees are passed as arguments, they are treated as ordinary
2120 variables in the invoked function. Subsequent changes to the pointer
2121 will not change the base address of the array that was passed.
2123 @node CONVERT specifier
2124 @subsection @code{CONVERT} specifier
2125 @cindex @code{CONVERT} specifier
2127 GNU Fortran allows the conversion of unformatted data between little-
2128 and big-endian representation to facilitate moving of data
2129 between different systems. The conversion can be indicated with
2130 the @code{CONVERT} specifier on the @code{OPEN} statement.
2131 @xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying
2132 the data format via an environment variable.
2134 Valid values for @code{CONVERT} are:
2136 @item @code{CONVERT='NATIVE'} Use the native format. This is the default.
2137 @item @code{CONVERT='SWAP'} Swap between little- and big-endian.
2138 @item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation
2139 for unformatted files.
2140 @item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for
2144 Using the option could look like this:
2146 open(file='big.dat',form='unformatted',access='sequential', &
2147 convert='big_endian')
2150 The value of the conversion can be queried by using
2151 @code{INQUIRE(CONVERT=ch)}. The values returned are
2152 @code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}.
2154 @code{CONVERT} works between big- and little-endian for
2155 @code{INTEGER} values of all supported kinds and for @code{REAL}
2156 on IEEE systems of kinds 4 and 8. Conversion between different
2157 ``extended double'' types on different architectures such as
2158 m68k and x86_64, which GNU Fortran
2159 supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will
2162 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
2163 environment variable will override the CONVERT specifier in the
2164 open statement}. This is to give control over data formats to
2165 users who do not have the source code of their program available.
2167 Using anything but the native representation for unformatted data
2168 carries a significant speed overhead. If speed in this area matters
2169 to you, it is best if you use this only for data that needs to be
2176 OpenMP (Open Multi-Processing) is an application programming
2177 interface (API) that supports multi-platform shared memory
2178 multiprocessing programming in C/C++ and Fortran on many
2179 architectures, including Unix and Microsoft Windows platforms.
2180 It consists of a set of compiler directives, library routines,
2181 and environment variables that influence run-time behavior.
2183 GNU Fortran strives to be compatible to the
2184 @uref{http://openmp.org/wp/openmp-specifications/,
2185 OpenMP Application Program Interface v4.5}.
2187 To enable the processing of the OpenMP directive @code{!$omp} in
2188 free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp}
2189 directives in fixed form; the @code{!$} conditional compilation sentinels
2190 in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels
2191 in fixed form, @command{gfortran} needs to be invoked with the
2192 @option{-fopenmp}. This also arranges for automatic linking of the
2193 GNU Offloading and Multi Processing Runtime Library
2194 @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
2197 The OpenMP Fortran runtime library routines are provided both in a
2198 form of a Fortran 90 module named @code{omp_lib} and in a form of
2199 a Fortran @code{include} file named @file{omp_lib.h}.
2201 An example of a parallelized loop taken from Appendix A.1 of
2202 the OpenMP Application Program Interface v2.5:
2204 SUBROUTINE A1(N, A, B)
2207 !$OMP PARALLEL DO !I is private by default
2209 B(I) = (A(I) + A(I-1)) / 2.0
2211 !$OMP END PARALLEL DO
2218 @option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays
2219 will be allocated on the stack. When porting existing code to OpenMP,
2220 this may lead to surprising results, especially to segmentation faults
2221 if the stacksize is limited.
2224 On glibc-based systems, OpenMP enabled applications cannot be statically
2225 linked due to limitations of the underlying pthreads-implementation. It
2226 might be possible to get a working solution if
2227 @command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added
2228 to the command line. However, this is not supported by @command{gcc} and
2229 thus not recommended.
2236 OpenACC is an application programming interface (API) that supports
2237 offloading of code to accelerator devices. It consists of a set of
2238 compiler directives, library routines, and environment variables that
2239 influence run-time behavior.
2241 GNU Fortran strives to be compatible to the
2242 @uref{http://www.openacc.org/, OpenACC Application Programming
2245 To enable the processing of the OpenACC directive @code{!$acc} in
2246 free-form source code; the @code{c$acc}, @code{*$acc} and @code{!$acc}
2247 directives in fixed form; the @code{!$} conditional compilation
2248 sentinels in free form; and the @code{c$}, @code{*$} and @code{!$}
2249 sentinels in fixed form, @command{gfortran} needs to be invoked with
2250 the @option{-fopenacc}. This also arranges for automatic linking of
2251 the GNU Offloading and Multi Processing Runtime Library
2252 @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
2255 The OpenACC Fortran runtime library routines are provided both in a
2256 form of a Fortran 90 module named @code{openacc} and in a form of a
2257 Fortran @code{include} file named @file{openacc_lib.h}.
2259 @node Argument list functions
2260 @subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC}
2261 @cindex argument list functions
2266 GNU Fortran supports argument list functions @code{%VAL}, @code{%REF}
2267 and @code{%LOC} statements, for backward compatibility with g77.
2268 It is recommended that these should be used only for code that is
2269 accessing facilities outside of GNU Fortran, such as operating system
2270 or windowing facilities. It is best to constrain such uses to isolated
2271 portions of a program--portions that deal specifically and exclusively
2272 with low-level, system-dependent facilities. Such portions might well
2273 provide a portable interface for use by the program as a whole, but are
2274 themselves not portable, and should be thoroughly tested each time they
2275 are rebuilt using a new compiler or version of a compiler.
2277 @code{%VAL} passes a scalar argument by value, @code{%REF} passes it by
2278 reference and @code{%LOC} passes its memory location. Since gfortran
2279 already passes scalar arguments by reference, @code{%REF} is in effect
2280 a do-nothing. @code{%LOC} has the same effect as a Fortran pointer.
2282 An example of passing an argument by value to a C subroutine foo.:
2285 C prototype void foo_ (float x);
2294 For details refer to the g77 manual
2295 @uref{https://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}.
2297 Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the
2298 GNU Fortran testsuite are worth a look.
2300 @node Read/Write after EOF marker
2301 @subsection Read/Write after EOF marker
2303 @cindex @code{BACKSPACE}
2304 @cindex @code{REWIND}
2306 Some legacy codes rely on allowing @code{READ} or @code{WRITE} after the
2307 EOF file marker in order to find the end of a file. GNU Fortran normally
2308 rejects these codes with a run-time error message and suggests the user
2309 consider @code{BACKSPACE} or @code{REWIND} to properly position
2310 the file before the EOF marker. As an extension, the run-time error may
2311 be disabled using -std=legacy.
2314 @node STRUCTURE and RECORD
2315 @subsection @code{STRUCTURE} and @code{RECORD}
2316 @cindex @code{STRUCTURE}
2317 @cindex @code{RECORD}
2319 Record structures are a pre-Fortran-90 vendor extension to create
2320 user-defined aggregate data types. Support for record structures in GNU
2321 Fortran can be enabled with the @option{-fdec-structure} compile flag.
2322 If you have a choice, you should instead use Fortran 90's ``derived types'',
2323 which have a different syntax.
2325 In many cases, record structures can easily be converted to derived types.
2326 To convert, replace @code{STRUCTURE /}@var{structure-name}@code{/}
2327 by @code{TYPE} @var{type-name}. Additionally, replace
2328 @code{RECORD /}@var{structure-name}@code{/} by
2329 @code{TYPE(}@var{type-name}@code{)}. Finally, in the component access,
2330 replace the period (@code{.}) by the percent sign (@code{%}).
2332 Here is an example of code using the non portable record structure syntax:
2335 ! Declaring a structure named ``item'' and containing three fields:
2336 ! an integer ID, an description string and a floating-point price.
2339 CHARACTER(LEN=200) description
2343 ! Define two variables, an single record of type ``item''
2344 ! named ``pear'', and an array of items named ``store_catalog''
2345 RECORD /item/ pear, store_catalog(100)
2347 ! We can directly access the fields of both variables
2349 pear.description = "juicy D'Anjou pear"
2351 store_catalog(7).id = 7831
2352 store_catalog(7).description = "milk bottle"
2353 store_catalog(7).price = 1.2
2355 ! We can also manipulate the whole structure
2356 store_catalog(12) = pear
2357 print *, store_catalog(12)
2361 This code can easily be rewritten in the Fortran 90 syntax as following:
2364 ! ``STRUCTURE /name/ ... END STRUCTURE'' becomes
2365 ! ``TYPE name ... END TYPE''
2368 CHARACTER(LEN=200) description
2372 ! ``RECORD /name/ variable'' becomes ``TYPE(name) variable''
2373 TYPE(item) pear, store_catalog(100)
2375 ! Instead of using a dot (.) to access fields of a record, the
2376 ! standard syntax uses a percent sign (%)
2378 pear%description = "juicy D'Anjou pear"
2380 store_catalog(7)%id = 7831
2381 store_catalog(7)%description = "milk bottle"
2382 store_catalog(7)%price = 1.2
2384 ! Assignments of a whole variable do not change
2385 store_catalog(12) = pear
2386 print *, store_catalog(12)
2390 GNU Fortran implements STRUCTURES like derived types with the following
2391 rules and exceptions:
2394 @item Structures act like derived types with the @code{SEQUENCE} attribute.
2395 Otherwise they may contain no specifiers.
2397 @item Structures may contain a special field with the name @code{%FILL}.
2398 This will create an anonymous component which cannot be accessed but occupies
2399 space just as if a component of the same type was declared in its place, useful
2400 for alignment purposes. As an example, the following structure will consist
2401 of at least sixteen bytes:
2411 @item Structures may share names with other symbols. For example, the following
2412 is invalid for derived types, but valid for structures:
2418 record /header/ header
2421 @item Structure types may be declared nested within another parent structure.
2424 structure /type-name/
2426 structure [/<type-name>/] <field-list>
2430 The type name may be ommitted, in which case the structure type itself is
2431 anonymous, and other structures of the same type cannot be instantiated. The
2432 following shows some examples:
2435 structure /appointment/
2436 ! nested structure definition: app_time is an array of two 'time'
2437 structure /time/ app_time (2)
2438 integer(1) hour, minute
2443 ! The 'time' structure is still usable
2449 structure /appointment/
2450 ! anonymous nested structure definition
2451 structure start, end
2452 integer(1) hour, minute
2458 @item Structures may contain @code{UNION} blocks. For more detail see the
2459 section on @ref{UNION and MAP}.
2461 @item Structures support old-style initialization of components, like
2462 those described in @ref{Old-style variable initialization}. For array
2463 initializers, an initializer may contain a repeat specification of the form
2464 @code{<literal-integer> * <constant-initializer>}. The value of the integer
2465 indicates the number of times to repeat the constant initializer when expanding
2466 the initializer list.
2470 @subsection @code{UNION} and @code{MAP}
2471 @cindex @code{UNION}
2474 Unions are an old vendor extension which were commonly used with the
2475 non-standard @ref{STRUCTURE and RECORD} extensions. Use of @code{UNION} and
2476 @code{MAP} is automatically enabled with @option{-fdec-structure}.
2478 A @code{UNION} declaration occurs within a structure; within the definition of
2479 each union is a number of @code{MAP} blocks. Each @code{MAP} shares storage
2480 with its sibling maps (in the same union), and the size of the union is the
2481 size of the largest map within it, just as with unions in C. The major
2482 difference is that component references do not indicate which union or map the
2483 component is in (the compiler gets to figure that out).
2485 Here is a small example:
2490 character(2) w0, w1, w2
2498 record /myunion/ rec
2499 ! After this assignment...
2502 ! The following is true:
2508 The two maps share memory, and the size of the union is ultimately six bytes:
2511 0 1 2 3 4 5 6 Byte offset
2512 -------------------------------
2514 -------------------------------
2517 \-------/ \-------/ \-------/
2520 \---------------------------/
2523 Following is an example mirroring the layout of an Intel x86_64 register:
2532 character(8) rh ! rah
2535 character(8) rl ! ral
2538 character(8) ex ! eax
2541 character(4) eh ! eah
2544 character(4) el ! eal
2561 ! After this assignment...
2562 a.rx = 'AAAAAAAA.BBB.C.D'
2564 ! The following is true:
2565 a.rx === 'AAAAAAAA.BBB.C.D'
2576 @node Type variants for integer intrinsics
2577 @subsection Type variants for integer intrinsics
2578 @cindex intrinsics, integer
2580 Similar to the D/C prefixes to real functions to specify the input/output
2581 types, GNU Fortran offers B/I/J/K prefixes to integer functions for
2582 compatibility with DEC programs. The types implied by each are:
2585 @code{B} - @code{INTEGER(kind=1)}
2586 @code{I} - @code{INTEGER(kind=2)}
2587 @code{J} - @code{INTEGER(kind=4)}
2588 @code{K} - @code{INTEGER(kind=8)}
2591 GNU Fortran supports these with the flag @option{-fdec-intrinsic-ints}.
2592 Intrinsics for which prefixed versions are available and in what form are noted
2593 in @ref{Intrinsic Procedures}. The complete list of supported intrinsics is
2596 @multitable @columnfractions .2 .2 .2 .2 .2
2598 @headitem Intrinsic @tab B @tab I @tab J @tab K
2600 @item @code{@ref{ABS}}
2601 @tab @code{BABS} @tab @code{IIABS} @tab @code{JIABS} @tab @code{KIABS}
2602 @item @code{@ref{BTEST}}
2603 @tab @code{BBTEST} @tab @code{BITEST} @tab @code{BJTEST} @tab @code{BKTEST}
2604 @item @code{@ref{IAND}}
2605 @tab @code{BIAND} @tab @code{IIAND} @tab @code{JIAND} @tab @code{KIAND}
2606 @item @code{@ref{IBCLR}}
2607 @tab @code{BBCLR} @tab @code{IIBCLR} @tab @code{JIBCLR} @tab @code{KIBCLR}
2608 @item @code{@ref{IBITS}}
2609 @tab @code{BBITS} @tab @code{IIBITS} @tab @code{JIBITS} @tab @code{KIBITS}
2610 @item @code{@ref{IBSET}}
2611 @tab @code{BBSET} @tab @code{IIBSET} @tab @code{JIBSET} @tab @code{KIBSET}
2612 @item @code{@ref{IEOR}}
2613 @tab @code{BIEOR} @tab @code{IIEOR} @tab @code{JIEOR} @tab @code{KIEOR}
2614 @item @code{@ref{IOR}}
2615 @tab @code{BIOR} @tab @code{IIOR} @tab @code{JIOR} @tab @code{KIOR}
2616 @item @code{@ref{ISHFT}}
2617 @tab @code{BSHFT} @tab @code{IISHFT} @tab @code{JISHFT} @tab @code{KISHFT}
2618 @item @code{@ref{ISHFTC}}
2619 @tab @code{BSHFTC} @tab @code{IISHFTC} @tab @code{JISHFTC} @tab @code{KISHFTC}
2620 @item @code{@ref{MOD}}
2621 @tab @code{BMOD} @tab @code{IMOD} @tab @code{JMOD} @tab @code{KMOD}
2622 @item @code{@ref{NOT}}
2623 @tab @code{BNOT} @tab @code{INOT} @tab @code{JNOT} @tab @code{KNOT}
2624 @item @code{@ref{REAL}}
2625 @tab @code{--} @tab @code{FLOATI} @tab @code{FLOATJ} @tab @code{FLOATK}
2628 @node AUTOMATIC and STATIC attributes
2629 @subsection @code{AUTOMATIC} and @code{STATIC} attributes
2630 @cindex variable attributes
2631 @cindex @code{AUTOMATIC}
2632 @cindex @code{STATIC}
2634 With @option{-fdec-static} GNU Fortran supports the DEC extended attributes
2635 @code{STATIC} and @code{AUTOMATIC} to provide explicit specification of entity
2636 storage. These follow the syntax of the Fortran standard @code{SAVE} attribute.
2638 @code{STATIC} is exactly equivalent to @code{SAVE}, and specifies that
2639 an entity should be allocated in static memory. As an example, @code{STATIC}
2640 local variables will retain their values across multiple calls to a function.
2642 Entities marked @code{AUTOMATIC} will be stack automatic whenever possible.
2643 @code{AUTOMATIC} is the default for local variables smaller than
2644 @option{-fmax-stack-var-size}, unless @option{-fno-automatic} is given. This
2645 attribute overrides @option{-fno-automatic}, @option{-fmax-stack-var-size}, and
2646 blanket @code{SAVE} statements.
2653 integer, automatic :: i ! automatic variable
2654 integer x, y ! static variables
2661 integer a, b, c, x, y, z
2665 ! a, b, c, and z are automatic
2666 ! x and y are static
2670 ! Compiled with -fno-automatic
2674 ! a is automatic; b, c, and d are static
2678 @node Extended math intrinsics
2679 @subsection Extended math intrinsics
2680 @cindex intrinsics, math
2681 @cindex intrinsics, trigonometric functions
2683 GNU Fortran supports an extended list of mathematical intrinsics with the
2684 compile flag @option{-fdec-math} for compatability with legacy code.
2685 These intrinsics are described fully in @ref{Intrinsic Procedures} where it is
2686 noted that they are extensions and should be avoided whenever possible.
2688 Specifically, @option{-fdec-math} enables the @ref{COTAN} intrinsic, and
2689 trigonometric intrinsics which accept or produce values in degrees instead of
2690 radians. Here is a summary of the new intrinsics:
2692 @multitable @columnfractions .5 .5
2693 @headitem Radians @tab Degrees
2694 @item @code{@ref{ACOS}} @tab @code{@ref{ACOSD}}*
2695 @item @code{@ref{ASIN}} @tab @code{@ref{ASIND}}*
2696 @item @code{@ref{ATAN}} @tab @code{@ref{ATAND}}*
2697 @item @code{@ref{ATAN2}} @tab @code{@ref{ATAN2D}}*
2698 @item @code{@ref{COS}} @tab @code{@ref{COSD}}*
2699 @item @code{@ref{COTAN}}* @tab @code{@ref{COTAND}}*
2700 @item @code{@ref{SIN}} @tab @code{@ref{SIND}}*
2701 @item @code{@ref{TAN}} @tab @code{@ref{TAND}}*
2704 * Enabled with @option{-fdec-math}.
2706 For advanced users, it may be important to know the implementation of these
2707 functions. They are simply wrappers around the standard radian functions, which
2708 have more accurate builtin versions. These functions convert their arguments
2709 (or results) to degrees (or radians) by taking the value modulus 360 (or 2*pi)
2710 and then multiplying it by a constant radian-to-degree (or degree-to-radian)
2711 factor, as appropriate. The factor is computed at compile-time as 180/pi (or
2714 @node Form feed as whitespace
2715 @subsection Form feed as whitespace
2716 @cindex form feed whitespace
2718 Historically, legacy compilers allowed insertion of form feed characters ('\f',
2719 ASCII 0xC) at the beginning of lines for formatted output to line printers,
2720 though the Fortran standard does not mention this. GNU Fortran supports the
2721 interpretation of form feed characters in source as whitespace for
2724 @node TYPE as an alias for PRINT
2725 @subsection TYPE as an alias for PRINT
2726 @cindex type alias print
2727 For compatibility, GNU Fortran will interpret @code{TYPE} statements as
2728 @code{PRINT} statements with the flag @option{-fdec}. With this flag asserted,
2729 the following two examples are equivalent:
2732 TYPE *, 'hello world'
2736 PRINT *, 'hello world'
2739 @node %LOC as an rvalue
2740 @subsection %LOC as an rvalue
2742 Normally @code{%LOC} is allowed only in parameter lists. However the intrinsic
2743 function @code{LOC} does the same thing, and is usable as the right-hand-side of
2744 assignments. For compatibility, GNU Fortran supports the use of @code{%LOC} as
2745 an alias for the builtin @code{LOC} with @option{-std=legacy}. With this
2746 feature enabled the following two examples are equivalent:
2759 @node .XOR. operator
2760 @subsection .XOR. operator
2761 @cindex operators, xor
2763 GNU Fortran supports @code{.XOR.} as a logical operator with @code{-std=legacy}
2764 for compatibility with legacy code. @code{.XOR.} is equivalent to
2765 @code{.NEQV.}. That is, the output is true if and only if the inputs differ.
2767 @node Bitwise logical operators
2768 @subsection Bitwise logical operators
2769 @cindex logical, bitwise
2771 With @option{-fdec}, GNU Fortran relaxes the type constraints on
2772 logical operators to allow integer operands, and performs the corresponding
2773 bitwise operation instead. This flag is for compatibility only, and should be
2774 avoided in new code. Consider:
2783 In this example, compiled with @option{-fdec}, GNU Fortran will
2784 replace the @code{.AND.} operation with a call to the intrinsic
2785 @code{@ref{IAND}} function, yielding the bitwise-and of @code{i} and @code{j}.
2787 Note that this conversion will occur if at least one operand is of integral
2788 type. As a result, a logical operand will be converted to an integer when the
2789 other operand is an integer in a logical operation. In this case,
2790 @code{.TRUE.} is converted to @code{1} and @code{.FALSE.} to @code{0}.
2792 Here is the mapping of logical operator to bitwise intrinsic used with
2795 @multitable @columnfractions .25 .25 .5
2796 @headitem Operator @tab Intrinsic @tab Bitwise operation
2797 @item @code{.NOT.} @tab @code{@ref{NOT}} @tab complement
2798 @item @code{.AND.} @tab @code{@ref{IAND}} @tab intersection
2799 @item @code{.OR.} @tab @code{@ref{IOR}} @tab union
2800 @item @code{.NEQV.} @tab @code{@ref{IEOR}} @tab exclusive or
2801 @item @code{.EQV.} @tab @code{@ref{NOT}(@ref{IEOR})} @tab complement of exclusive or
2804 @node Extended I/O specifiers
2805 @subsection Extended I/O specifiers
2806 @cindex @code{CARRIAGECONTROL}
2807 @cindex @code{READONLY}
2808 @cindex @code{SHARE}
2809 @cindex @code{SHARED}
2810 @cindex @code{NOSHARED}
2811 @cindex I/O specifiers
2813 GNU Fortran supports the additional legacy I/O specifiers
2814 @code{CARRIAGECONTROL}, @code{READONLY}, and @code{SHARE} with the
2815 compile flag @option{-fdec}, for compatibility.
2818 @item CARRIAGECONTROL
2819 The @code{CARRIAGECONTROL} specifier allows a user to control line
2820 termination settings between output records for an I/O unit. The specifier has
2821 no meaning for readonly files. When @code{CARRAIGECONTROL} is specified upon
2822 opening a unit for formatted writing, the exact @code{CARRIAGECONTROL} setting
2823 determines what characters to write between output records. The syntax is:
2826 OPEN(..., CARRIAGECONTROL=cc)
2829 Where @emph{cc} is a character expression that evaluates to one of the
2832 @multitable @columnfractions .2 .8
2833 @item @code{'LIST'} @tab One line feed between records (default)
2834 @item @code{'FORTRAN'} @tab Legacy interpretation of the first character (see below)
2835 @item @code{'NONE'} @tab No separator between records
2838 With @code{CARRIAGECONTROL='FORTRAN'}, when a record is written, the first
2839 character of the input record is not written, and instead determines the output
2840 record separator as follows:
2842 @multitable @columnfractions .3 .3 .4
2843 @headitem Leading character @tab Meaning @tab Output separating character(s)
2844 @item @code{'+'} @tab Overprinting @tab Carriage return only
2845 @item @code{'-'} @tab New line @tab Line feed and carriage return
2846 @item @code{'0'} @tab Skip line @tab Two line feeds and carriage return
2847 @item @code{'1'} @tab New page @tab Form feed and carriage return
2848 @item @code{'$'} @tab Prompting @tab Line feed (no carriage return)
2849 @item @code{CHAR(0)} @tab Overprinting (no advance) @tab None
2853 The @code{READONLY} specifier may be given upon opening a unit, and is
2854 equivalent to specifying @code{ACTION='READ'}, except that the file may not be
2855 deleted on close (i.e. @code{CLOSE} with @code{STATUS="DELETE"}). The syntax
2859 @code{OPEN(..., READONLY)}
2863 The @code{SHARE} specifier allows system-level locking on a unit upon opening
2864 it for controlled access from multiple processes/threads. The @code{SHARE}
2865 specifier has several forms:
2873 Where @emph{sh} in the first form is a character expression that evaluates to
2874 a value as seen in the table below. The latter two forms are aliases
2875 for particular values of @emph{sh}:
2877 @multitable @columnfractions .3 .3 .4
2878 @headitem Explicit form @tab Short form @tab Meaning
2879 @item @code{SHARE='DENYRW'} @tab @code{NOSHARED} @tab Exclusive (write) lock
2880 @item @code{SHARE='DENYNONE'} @tab @code{SHARED} @tab Shared (read) lock
2883 In general only one process may hold an exclusive (write) lock for a given file
2884 at a time, whereas many processes may hold shared (read) locks for the same
2887 The behavior of locking may vary with your operating system. On POSIX systems,
2888 locking is implemented with @code{fcntl}. Consult your corresponding operating
2889 system's manual pages for further details. Locking via @code{SHARE=} is not
2890 supported on other systems.
2894 @node Legacy PARAMETER statements
2895 @subsection Legacy PARAMETER statements
2898 For compatibility, GNU Fortran supports legacy PARAMETER statements without
2899 parentheses with @option{-std=legacy}. A warning is emitted if used with
2900 @option{-std=gnu}, and an error is acknowledged with a real Fortran standard
2901 flag (@option{-std=f95}, etc...). These statements take the following form:
2905 parameter e = 2.718282
2910 @node Default exponents
2911 @subsection Default exponents
2914 For compatibility, GNU Fortran supports a default exponent of zero in real
2915 constants with @option{-fdec}. For example, @code{9e} would be
2916 interpreted as @code{9e0}, rather than an error.
2919 @node Extensions not implemented in GNU Fortran
2920 @section Extensions not implemented in GNU Fortran
2921 @cindex extensions, not implemented
2923 The long history of the Fortran language, its wide use and broad
2924 userbase, the large number of different compiler vendors and the lack of
2925 some features crucial to users in the first standards have lead to the
2926 existence of a number of important extensions to the language. While
2927 some of the most useful or popular extensions are supported by the GNU
2928 Fortran compiler, not all existing extensions are supported. This section
2929 aims at listing these extensions and offering advice on how best make
2930 code that uses them running with the GNU Fortran compiler.
2932 @c More can be found here:
2933 @c -- https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html
2934 @c -- the list of Fortran and libgfortran bugs closed as WONTFIX:
2935 @c http://tinyurl.com/2u4h5y
2938 * ENCODE and DECODE statements::
2939 * Variable FORMAT expressions::
2940 @c * TYPE and ACCEPT I/O Statements::
2941 @c * DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers::
2942 @c * Omitted arguments in procedure call::
2943 * Alternate complex function syntax::
2944 * Volatile COMMON blocks::
2945 * OPEN( ... NAME=)::
2946 * Q edit descriptor::
2949 @node ENCODE and DECODE statements
2950 @subsection @code{ENCODE} and @code{DECODE} statements
2951 @cindex @code{ENCODE}
2952 @cindex @code{DECODE}
2954 GNU Fortran does not support the @code{ENCODE} and @code{DECODE}
2955 statements. These statements are best replaced by @code{READ} and
2956 @code{WRITE} statements involving internal files (@code{CHARACTER}
2957 variables and arrays), which have been part of the Fortran standard since
2958 Fortran 77. For example, replace a code fragment like
2963 c ... Code that sets LINE
2964 DECODE (80, 9000, LINE) A, B, C
2965 9000 FORMAT (1X, 3(F10.5))
2972 CHARACTER(LEN=80) LINE
2974 c ... Code that sets LINE
2975 READ (UNIT=LINE, FMT=9000) A, B, C
2976 9000 FORMAT (1X, 3(F10.5))
2979 Similarly, replace a code fragment like
2984 c ... Code that sets A, B and C
2985 ENCODE (80, 9000, LINE) A, B, C
2986 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2993 CHARACTER(LEN=80) LINE
2995 c ... Code that sets A, B and C
2996 WRITE (UNIT=LINE, FMT=9000) A, B, C
2997 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
3001 @node Variable FORMAT expressions
3002 @subsection Variable @code{FORMAT} expressions
3003 @cindex @code{FORMAT}
3005 A variable @code{FORMAT} expression is format statement which includes
3006 angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU
3007 Fortran does not support this legacy extension. The effect of variable
3008 format expressions can be reproduced by using the more powerful (and
3009 standard) combination of internal output and string formats. For example,
3010 replace a code fragment like this:
3021 c Variable declaration
3022 CHARACTER(LEN=20) FMT
3024 c Other code here...
3026 WRITE(FMT,'("(I", I0, ")")') N+1
3034 c Variable declaration
3035 CHARACTER(LEN=20) FMT
3037 c Other code here...
3040 WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1
3044 @node Alternate complex function syntax
3045 @subsection Alternate complex function syntax
3046 @cindex Complex function
3048 Some Fortran compilers, including @command{g77}, let the user declare
3049 complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as
3050 well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy
3051 extensions. @command{gfortran} accepts the latter form, which is more
3052 common, but not the former.
3055 @node Volatile COMMON blocks
3056 @subsection Volatile @code{COMMON} blocks
3057 @cindex @code{VOLATILE}
3058 @cindex @code{COMMON}
3060 Some Fortran compilers, including @command{g77}, let the user declare
3061 @code{COMMON} with the @code{VOLATILE} attribute. This is
3062 invalid standard Fortran syntax and is not supported by
3063 @command{gfortran}. Note that @command{gfortran} accepts
3064 @code{VOLATILE} variables in @code{COMMON} blocks since revision 4.3.
3067 @node OPEN( ... NAME=)
3068 @subsection @code{OPEN( ... NAME=)}
3071 Some Fortran compilers, including @command{g77}, let the user declare
3072 @code{OPEN( ... NAME=)}. This is
3073 invalid standard Fortran syntax and is not supported by
3074 @command{gfortran}. @code{OPEN( ... NAME=)} should be replaced
3075 with @code{OPEN( ... FILE=)}.
3077 @node Q edit descriptor
3078 @subsection @code{Q} edit descriptor
3079 @cindex @code{Q} edit descriptor
3081 Some Fortran compilers provide the @code{Q} edit descriptor, which
3082 transfers the number of characters left within an input record into an
3085 A direct replacement of the @code{Q} edit descriptor is not available
3086 in @command{gfortran}. How to replicate its functionality using
3087 standard-conforming code depends on what the intent of the original
3090 Options to replace @code{Q} may be to read the whole line into a
3091 character variable and then counting the number of non-blank
3092 characters left using @code{LEN_TRIM}. Another method may be to use
3093 formatted stream, read the data up to the position where the @code{Q}
3094 descriptor occurred, use @code{INQUIRE} to get the file position,
3095 count the characters up to the next @code{NEW_LINE} and then start
3096 reading from the position marked previously.
3099 @c ---------------------------------------------------------------------
3100 @c ---------------------------------------------------------------------
3101 @c Mixed-Language Programming
3102 @c ---------------------------------------------------------------------
3104 @node Mixed-Language Programming
3105 @chapter Mixed-Language Programming
3106 @cindex Interoperability
3107 @cindex Mixed-language programming
3110 * Interoperability with C::
3111 * GNU Fortran Compiler Directives::
3112 * Non-Fortran Main Program::
3113 * Naming and argument-passing conventions::
3116 This chapter is about mixed-language interoperability, but also applies
3117 if one links Fortran code compiled by different compilers. In most cases,
3118 use of the C Binding features of the Fortran 2003 standard is sufficient,
3119 and their use is highly recommended.
3122 @node Interoperability with C
3123 @section Interoperability with C
3127 * Derived Types and struct::
3128 * Interoperable Global Variables::
3129 * Interoperable Subroutines and Functions::
3130 * Working with Pointers::
3131 * Further Interoperability of Fortran with C::
3134 Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a
3135 standardized way to generate procedure and derived-type
3136 declarations and global variables which are interoperable with C
3137 (ISO/IEC 9899:1999). The @code{bind(C)} attribute has been added
3138 to inform the compiler that a symbol shall be interoperable with C;
3139 also, some constraints are added. Note, however, that not
3140 all C features have a Fortran equivalent or vice versa. For instance,
3141 neither C's unsigned integers nor C's functions with variable number
3142 of arguments have an equivalent in Fortran.
3144 Note that array dimensions are reversely ordered in C and that arrays in
3145 C always start with index 0 while in Fortran they start by default with
3146 1. Thus, an array declaration @code{A(n,m)} in Fortran matches
3147 @code{A[m][n]} in C and accessing the element @code{A(i,j)} matches
3148 @code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]};
3149 assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}).
3151 @node Intrinsic Types
3152 @subsection Intrinsic Types
3154 In order to ensure that exactly the same variable type and kind is used
3155 in C and Fortran, the named constants shall be used which are defined in the
3156 @code{ISO_C_BINDING} intrinsic module. That module contains named constants
3157 for kind parameters and character named constants for the escape sequences
3158 in C. For a list of the constants, see @ref{ISO_C_BINDING}.
3160 For logical types, please note that the Fortran standard only guarantees
3161 interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
3162 logicals and C99 defines that @code{true} has the value 1 and @code{false}
3163 the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL}
3164 (with any kind parameter) gives an undefined result. (Passing other integer
3165 values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the
3166 integer is explicitly or implicitly casted to @code{_Bool}.)
3170 @node Derived Types and struct
3171 @subsection Derived Types and struct
3173 For compatibility of derived types with @code{struct}, one needs to use
3174 the @code{BIND(C)} attribute in the type declaration. For instance, the
3175 following type declaration
3179 TYPE, BIND(C) :: myType
3180 INTEGER(C_INT) :: i1, i2
3181 INTEGER(C_SIGNED_CHAR) :: i3
3182 REAL(C_DOUBLE) :: d1
3183 COMPLEX(C_FLOAT_COMPLEX) :: c1
3184 CHARACTER(KIND=C_CHAR) :: str(5)
3188 matches the following @code{struct} declaration in C
3193 /* Note: "char" might be signed or unsigned. */
3201 Derived types with the C binding attribute shall not have the @code{sequence}
3202 attribute, type parameters, the @code{extends} attribute, nor type-bound
3203 procedures. Every component must be of interoperable type and kind and may not
3204 have the @code{pointer} or @code{allocatable} attribute. The names of the
3205 components are irrelevant for interoperability.
3207 As there exist no direct Fortran equivalents, neither unions nor structs
3208 with bit field or variable-length array members are interoperable.
3210 @node Interoperable Global Variables
3211 @subsection Interoperable Global Variables
3213 Variables can be made accessible from C using the C binding attribute,
3214 optionally together with specifying a binding name. Those variables
3215 have to be declared in the declaration part of a @code{MODULE},
3216 be of interoperable type, and have neither the @code{pointer} nor
3217 the @code{allocatable} attribute.
3223 integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag
3224 type(myType), bind(C) :: tp
3228 Here, @code{_MyProject_flags} is the case-sensitive name of the variable
3229 as seen from C programs while @code{global_flag} is the case-insensitive
3230 name as seen from Fortran. If no binding name is specified, as for
3231 @var{tp}, the C binding name is the (lowercase) Fortran binding name.
3232 If a binding name is specified, only a single variable may be after the
3233 double colon. Note of warning: You cannot use a global variable to
3234 access @var{errno} of the C library as the C standard allows it to be
3235 a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead.
3237 @node Interoperable Subroutines and Functions
3238 @subsection Interoperable Subroutines and Functions
3240 Subroutines and functions have to have the @code{BIND(C)} attribute to
3241 be compatible with C. The dummy argument declaration is relatively
3242 straightforward. However, one needs to be careful because C uses
3243 call-by-value by default while Fortran behaves usually similar to
3244 call-by-reference. Furthermore, strings and pointers are handled
3245 differently. Note that in Fortran 2003 and 2008 only explicit size
3246 and assumed-size arrays are supported but not assumed-shape or
3247 deferred-shape (i.e. allocatable or pointer) arrays. However, those
3248 are allowed since the Technical Specification 29113, see
3249 @ref{Further Interoperability of Fortran with C}
3251 To pass a variable by value, use the @code{VALUE} attribute.
3252 Thus, the following C prototype
3255 @code{int func(int i, int *j)}
3258 matches the Fortran declaration
3261 integer(c_int) function func(i,j)
3262 use iso_c_binding, only: c_int
3263 integer(c_int), VALUE :: i
3267 Note that pointer arguments also frequently need the @code{VALUE} attribute,
3268 see @ref{Working with Pointers}.
3270 Strings are handled quite differently in C and Fortran. In C a string
3271 is a @code{NUL}-terminated array of characters while in Fortran each string
3272 has a length associated with it and is thus not terminated (by e.g.
3273 @code{NUL}). For example, if one wants to use the following C function,
3277 void print_C(char *string) /* equivalent: char string[] */
3279 printf("%s\n", string);
3283 to print ``Hello World'' from Fortran, one can call it using
3286 use iso_c_binding, only: C_CHAR, C_NULL_CHAR
3288 subroutine print_c(string) bind(C, name="print_C")
3289 use iso_c_binding, only: c_char
3290 character(kind=c_char) :: string(*)
3291 end subroutine print_c
3293 call print_c(C_CHAR_"Hello World"//C_NULL_CHAR)
3296 As the example shows, one needs to ensure that the
3297 string is @code{NUL} terminated. Additionally, the dummy argument
3298 @var{string} of @code{print_C} is a length-one assumed-size
3299 array; using @code{character(len=*)} is not allowed. The example
3300 above uses @code{c_char_"Hello World"} to ensure the string
3301 literal has the right type; typically the default character
3302 kind and @code{c_char} are the same and thus @code{"Hello World"}
3303 is equivalent. However, the standard does not guarantee this.
3305 The use of strings is now further illustrated using the C library
3306 function @code{strncpy}, whose prototype is
3309 char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
3312 The function @code{strncpy} copies at most @var{n} characters from
3313 string @var{s2} to @var{s1} and returns @var{s1}. In the following
3314 example, we ignore the return value:
3319 character(len=30) :: str,str2
3321 ! Ignore the return value of strncpy -> subroutine
3322 ! "restrict" is always assumed if we do not pass a pointer
3323 subroutine strncpy(dest, src, n) bind(C)
3325 character(kind=c_char), intent(out) :: dest(*)
3326 character(kind=c_char), intent(in) :: src(*)
3327 integer(c_size_t), value, intent(in) :: n
3328 end subroutine strncpy
3330 str = repeat('X',30) ! Initialize whole string with 'X'
3331 call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, &
3332 len(c_char_"Hello World",kind=c_size_t))
3333 print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX"
3337 The intrinsic procedures are described in @ref{Intrinsic Procedures}.
3339 @node Working with Pointers
3340 @subsection Working with Pointers
3342 C pointers are represented in Fortran via the special opaque derived type
3343 @code{type(c_ptr)} (with private components). Thus one needs to
3344 use intrinsic conversion procedures to convert from or to C pointers.
3346 For some applications, using an assumed type (@code{TYPE(*)}) can be an
3347 alternative to a C pointer; see
3348 @ref{Further Interoperability of Fortran with C}.
3354 type(c_ptr) :: cptr1, cptr2
3355 integer, target :: array(7), scalar
3356 integer, pointer :: pa(:), ps
3357 cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the
3358 ! array is contiguous if required by the C
3360 cptr2 = c_loc(scalar)
3361 call c_f_pointer(cptr2, ps)
3362 call c_f_pointer(cptr2, pa, shape=[7])
3365 When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument
3368 If a pointer is a dummy-argument of an interoperable procedure, it usually
3369 has to be declared using the @code{VALUE} attribute. @code{void*}
3370 matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone
3371 matches @code{void**}.
3373 Procedure pointers are handled analogously to pointers; the C type is
3374 @code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are
3375 @code{C_F_PROCPOINTER} and @code{C_FUNLOC}.
3377 Let us consider two examples of actually passing a procedure pointer from
3378 C to Fortran and vice versa. Note that these examples are also very
3379 similar to passing ordinary pointers between both languages. First,
3380 consider this code in C:
3383 /* Procedure implemented in Fortran. */
3384 void get_values (void (*)(double));
3386 /* Call-back routine we want called from Fortran. */
3390 printf ("Number is %f.\n", x);
3393 /* Call Fortran routine and pass call-back to it. */
3397 get_values (&print_it);
3401 A matching implementation for @code{get_values} in Fortran, that correctly
3402 receives the procedure pointer from C and is able to call it, is given
3403 in the following @code{MODULE}:
3409 ! Define interface of call-back routine.
3411 SUBROUTINE callback (x)
3412 USE, INTRINSIC :: ISO_C_BINDING
3413 REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x
3414 END SUBROUTINE callback
3419 ! Define C-bound procedure.
3420 SUBROUTINE get_values (cproc) BIND(C)
3421 USE, INTRINSIC :: ISO_C_BINDING
3422 TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc
3424 PROCEDURE(callback), POINTER :: proc
3426 ! Convert C to Fortran procedure pointer.
3427 CALL C_F_PROCPOINTER (cproc, proc)
3430 CALL proc (1.0_C_DOUBLE)
3431 CALL proc (-42.0_C_DOUBLE)
3432 CALL proc (18.12_C_DOUBLE)
3433 END SUBROUTINE get_values
3438 Next, we want to call a C routine that expects a procedure pointer argument
3439 and pass it a Fortran procedure (which clearly must be interoperable!).
3440 Again, the C function may be:
3444 call_it (int (*func)(int), int arg)
3450 It can be used as in the following Fortran code:
3454 USE, INTRINSIC :: ISO_C_BINDING
3457 ! Define interface of C function.
3459 INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C)
3460 USE, INTRINSIC :: ISO_C_BINDING
3461 TYPE(C_FUNPTR), INTENT(IN), VALUE :: func
3462 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
3463 END FUNCTION call_it
3468 ! Define procedure passed to C function.
3469 ! It must be interoperable!
3470 INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C)
3471 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
3472 double_it = arg + arg
3473 END FUNCTION double_it
3476 SUBROUTINE foobar ()
3477 TYPE(C_FUNPTR) :: cproc
3478 INTEGER(KIND=C_INT) :: i
3480 ! Get C procedure pointer.
3481 cproc = C_FUNLOC (double_it)
3484 DO i = 1_C_INT, 10_C_INT
3485 PRINT *, call_it (cproc, i)
3487 END SUBROUTINE foobar
3492 @node Further Interoperability of Fortran with C
3493 @subsection Further Interoperability of Fortran with C
3495 The Technical Specification ISO/IEC TS 29113:2012 on further
3496 interoperability of Fortran with C extends the interoperability support
3497 of Fortran 2003 and Fortran 2008. Besides removing some restrictions
3498 and constraints, it adds assumed-type (@code{TYPE(*)}) and assumed-rank
3499 (@code{dimension}) variables and allows for interoperability of
3500 assumed-shape, assumed-rank and deferred-shape arrays, including
3501 allocatables and pointers.
3503 Note: Currently, GNU Fortran does not use internally the array descriptor
3504 (dope vector) as specified in the Technical Specification, but uses
3505 an array descriptor with different fields. Assumed type and assumed rank
3506 formal arguments are converted in the library to the specified form. The
3507 ISO_Fortran_binding API functions (also Fortran 2018 18.4) are implemented
3508 in libgfortran. Alternatively, the Chasm Language Interoperability Tools,
3509 @url{http://chasm-interop.sourceforge.net/}, provide an interface to GNU
3510 Fortran's array descriptor.
3512 The Technical Specification adds the following new features, which
3513 are supported by GNU Fortran:
3517 @item The @code{ASYNCHRONOUS} attribute has been clarified and
3518 extended to allow its use with asynchronous communication in
3519 user-provided libraries such as in implementations of the
3520 Message Passing Interface specification.
3522 @item Many constraints have been relaxed, in particular for
3523 the @code{C_LOC} and @code{C_F_POINTER} intrinsics.
3525 @item The @code{OPTIONAL} attribute is now allowed for dummy
3526 arguments; an absent argument matches a @code{NULL} pointer.
3528 @item Assumed types (@code{TYPE(*)}) have been added, which may
3529 only be used for dummy arguments. They are unlimited polymorphic
3530 but contrary to @code{CLASS(*)} they do not contain any type
3531 information, similar to C's @code{void *} pointers. Expressions
3532 of any type and kind can be passed; thus, it can be used as
3533 replacement for @code{TYPE(C_PTR)}, avoiding the use of
3534 @code{C_LOC} in the caller.
3536 Note, however, that @code{TYPE(*)} only accepts scalar arguments,
3537 unless the @code{DIMENSION} is explicitly specified. As
3538 @code{DIMENSION(*)} only supports array (including array elements) but
3539 no scalars, it is not a full replacement for @code{C_LOC}. On the
3540 other hand, assumed-type assumed-rank dummy arguments
3541 (@code{TYPE(*), DIMENSION(..)}) allow for both scalars and arrays, but
3542 require special code on the callee side to handle the array descriptor.
3544 @item Assumed-rank arrays (@code{DIMENSION(..)}) as dummy argument
3545 allow that scalars and arrays of any rank can be passed as actual
3546 argument. As the Technical Specification does not provide for direct
3547 means to operate with them, they have to be used either from the C side
3548 or be converted using @code{C_LOC} and @code{C_F_POINTER} to scalars
3549 or arrays of a specific rank. The rank can be determined using the
3550 @code{RANK} intrinisic.
3554 Currently unimplemented:
3558 @item GNU Fortran always uses an array descriptor, which does not
3559 match the one of the Technical Specification. The
3560 @code{ISO_Fortran_binding.h} header file and the C functions it
3561 specifies are not available.
3563 @item Using assumed-shape, assumed-rank and deferred-shape arrays in
3564 @code{BIND(C)} procedures is not fully supported. In particular,
3565 C interoperable strings of other length than one are not supported
3566 as this requires the new array descriptor.
3570 @node GNU Fortran Compiler Directives
3571 @section GNU Fortran Compiler Directives
3574 * ATTRIBUTES directive::
3575 * UNROLL directive::
3576 * BUILTIN directive::
3578 * VECTOR directive::
3579 * NOVECTOR directive::
3582 @node ATTRIBUTES directive
3583 @subsection ATTRIBUTES directive
3585 The Fortran standard describes how a conforming program shall
3586 behave; however, the exact implementation is not standardized. In order
3587 to allow the user to choose specific implementation details, compiler
3588 directives can be used to set attributes of variables and procedures
3589 which are not part of the standard. Whether a given attribute is
3590 supported and its exact effects depend on both the operating system and
3591 on the processor; see
3592 @ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)}
3595 For procedures and procedure pointers, the following attributes can
3596 be used to change the calling convention:
3599 @item @code{CDECL} -- standard C calling convention
3600 @item @code{STDCALL} -- convention where the called procedure pops the stack
3601 @item @code{FASTCALL} -- part of the arguments are passed via registers
3602 instead using the stack
3605 Besides changing the calling convention, the attributes also influence
3606 the decoration of the symbol name, e.g., by a leading underscore or by
3607 a trailing at-sign followed by the number of bytes on the stack. When
3608 assigning a procedure to a procedure pointer, both should use the same
3611 On some systems, procedures and global variables (module variables and
3612 @code{COMMON} blocks) need special handling to be accessible when they
3613 are in a shared library. The following attributes are available:
3616 @item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL
3617 @item @code{DLLIMPORT} -- reference the function or variable using a
3621 For dummy arguments, the @code{NO_ARG_CHECK} attribute can be used; in
3622 other compilers, it is also known as @code{IGNORE_TKR}. For dummy arguments
3623 with this attribute actual arguments of any type and kind (similar to
3624 @code{TYPE(*)}), scalars and arrays of any rank (no equivalent
3625 in Fortran standard) are accepted. As with @code{TYPE(*)}, the argument
3626 is unlimited polymorphic and no type information is available.
3627 Additionally, the argument may only be passed to dummy arguments
3628 with the @code{NO_ARG_CHECK} attribute and as argument to the
3629 @code{PRESENT} intrinsic function and to @code{C_LOC} of the
3630 @code{ISO_C_BINDING} module.
3632 Variables with @code{NO_ARG_CHECK} attribute shall be of assumed-type
3633 (@code{TYPE(*)}; recommended) or of type @code{INTEGER}, @code{LOGICAL},
3634 @code{REAL} or @code{COMPLEX}. They shall not have the @code{ALLOCATE},
3635 @code{CODIMENSION}, @code{INTENT(OUT)}, @code{POINTER} or @code{VALUE}
3636 attribute; furthermore, they shall be either scalar or of assumed-size
3637 (@code{dimension(*)}). As @code{TYPE(*)}, the @code{NO_ARG_CHECK} attribute
3638 requires an explicit interface.
3641 @item @code{NO_ARG_CHECK} -- disable the type, kind and rank checking
3645 The attributes are specified using the syntax
3647 @code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list}
3649 where in free-form source code only whitespace is allowed before @code{!GCC$}
3650 and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall
3651 start in the first column.
3653 For procedures, the compiler directives shall be placed into the body
3654 of the procedure; for variables and procedure pointers, they shall be in
3655 the same declaration part as the variable or procedure pointer.
3658 @node UNROLL directive
3659 @subsection UNROLL directive
3661 The syntax of the directive is
3663 @code{!GCC$ unroll N}
3665 You can use this directive to control how many times a loop should be unrolled.
3666 It must be placed immediately before a @code{DO} loop and applies only to the
3667 loop that follows. N is an integer constant specifying the unrolling factor.
3668 The values of 0 and 1 block any unrolling of the loop.
3671 @node BUILTIN directive
3672 @subsection BUILTIN directive
3674 The syntax of the directive is
3676 @code{!GCC$ BUILTIN (B) attributes simd FLAGS IF('target')}
3678 You can use this directive to define which middle-end built-ins provide vector
3679 implementations. @code{B} is name of the middle-end built-in. @code{FLAGS}
3680 are optional and must be either "(inbranch)" or "(notinbranch)".
3681 @code{IF} statement is optional and is used to filter multilib ABIs
3682 for the built-in that should be vectorized. Example usage:
3685 !GCC$ builtin (sinf) attributes simd (notinbranch) if('x86_64')
3688 The purpose of the directive is to provide an API among the GCC compiler and
3689 the GNU C Library which would define vector implementations of math routines.
3692 @node IVDEP directive
3693 @subsection IVDEP directive
3695 The syntax of the directive is
3699 This directive tells the compiler to ignore vector dependencies in the
3700 following loop. It must be placed immediately before a @code{DO} loop
3701 and applies only to the loop that follows.
3703 Sometimes the compiler may not have sufficient information to decide
3704 whether a particular loop is vectorizable due to potential
3705 dependencies between iterations. The purpose of the directive is to
3706 tell the compiler that vectorization is safe.
3708 This directive is intended for annotation of existing code. For new
3709 code it is recommended to consider OpenMP SIMD directives as potential
3713 @node VECTOR directive
3714 @subsection VECTOR directive
3716 The syntax of the directive is
3720 This directive tells the compiler to vectorize the following loop. It
3721 must be placed immediately before a @code{DO} loop and applies only to
3722 the loop that follows.
3725 @node NOVECTOR directive
3726 @subsection NOVECTOR directive
3728 The syntax of the directive is
3730 @code{!GCC$ novector}
3732 This directive tells the compiler to not vectorize the following loop.
3733 It must be placed immediately before a @code{DO} loop and applies only
3734 to the loop that follows.
3737 @node Non-Fortran Main Program
3738 @section Non-Fortran Main Program
3741 * _gfortran_set_args:: Save command-line arguments
3742 * _gfortran_set_options:: Set library option flags
3743 * _gfortran_set_convert:: Set endian conversion
3744 * _gfortran_set_record_marker:: Set length of record markers
3745 * _gfortran_set_fpe:: Set when a Floating Point Exception should be raised
3746 * _gfortran_set_max_subrecord_length:: Set subrecord length
3749 Even if you are doing mixed-language programming, it is very
3750 likely that you do not need to know or use the information in this
3751 section. Since it is about the internal structure of GNU Fortran,
3752 it may also change in GCC minor releases.
3754 When you compile a @code{PROGRAM} with GNU Fortran, a function
3755 with the name @code{main} (in the symbol table of the object file)
3756 is generated, which initializes the libgfortran library and then
3757 calls the actual program which uses the name @code{MAIN__}, for
3758 historic reasons. If you link GNU Fortran compiled procedures
3759 to, e.g., a C or C++ program or to a Fortran program compiled by
3760 a different compiler, the libgfortran library is not initialized
3761 and thus a few intrinsic procedures do not work properly, e.g.
3762 those for obtaining the command-line arguments.
3764 Therefore, if your @code{PROGRAM} is not compiled with
3765 GNU Fortran and the GNU Fortran compiled procedures require
3766 intrinsics relying on the library initialization, you need to
3767 initialize the library yourself. Using the default options,
3768 gfortran calls @code{_gfortran_set_args} and
3769 @code{_gfortran_set_options}. The initialization of the former
3770 is needed if the called procedures access the command line
3771 (and for backtracing); the latter sets some flags based on the
3772 standard chosen or to enable backtracing. In typical programs,
3773 it is not necessary to call any initialization function.
3775 If your @code{PROGRAM} is compiled with GNU Fortran, you shall
3776 not call any of the following functions. The libgfortran
3777 initialization functions are shown in C syntax but using C
3778 bindings they are also accessible from Fortran.
3781 @node _gfortran_set_args
3782 @subsection @code{_gfortran_set_args} --- Save command-line arguments
3783 @fnindex _gfortran_set_args
3784 @cindex libgfortran initialization, set_args
3787 @item @emph{Description}:
3788 @code{_gfortran_set_args} saves the command-line arguments; this
3789 initialization is required if any of the command-line intrinsics
3790 is called. Additionally, it shall be called if backtracing is
3791 enabled (see @code{_gfortran_set_options}).
3793 @item @emph{Syntax}:
3794 @code{void _gfortran_set_args (int argc, char *argv[])}
3796 @item @emph{Arguments}:
3797 @multitable @columnfractions .15 .70
3798 @item @var{argc} @tab number of command line argument strings
3799 @item @var{argv} @tab the command-line argument strings; argv[0]
3800 is the pathname of the executable itself.
3803 @item @emph{Example}:
3805 int main (int argc, char *argv[])
3807 /* Initialize libgfortran. */
3808 _gfortran_set_args (argc, argv);
3815 @node _gfortran_set_options
3816 @subsection @code{_gfortran_set_options} --- Set library option flags
3817 @fnindex _gfortran_set_options
3818 @cindex libgfortran initialization, set_options
3821 @item @emph{Description}:
3822 @code{_gfortran_set_options} sets several flags related to the Fortran
3823 standard to be used, whether backtracing should be enabled
3824 and whether range checks should be performed. The syntax allows for
3825 upward compatibility since the number of passed flags is specified; for
3826 non-passed flags, the default value is used. See also
3827 @pxref{Code Gen Options}. Please note that not all flags are actually
3830 @item @emph{Syntax}:
3831 @code{void _gfortran_set_options (int num, int options[])}
3833 @item @emph{Arguments}:
3834 @multitable @columnfractions .15 .70
3835 @item @var{num} @tab number of options passed
3836 @item @var{argv} @tab The list of flag values
3839 @item @emph{option flag list}:
3840 @multitable @columnfractions .15 .70
3841 @item @var{option}[0] @tab Allowed standard; can give run-time errors
3842 if e.g. an input-output edit descriptor is invalid in a given
3843 standard. Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1),
3844 @code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4),
3845 @code{GFC_STD_F95} (8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU}
3846 (32), @code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128),
3847 @code{GFC_STD_F2008_OBS} (256), @code{GFC_STD_F2008_TS} (512),
3848 @code{GFC_STD_F2018} (1024), @code{GFC_STD_F2018_OBS} (2048), and
3849 @code{GFC_STD=F2018_DEL} (4096). Default: @code{GFC_STD_F95_OBS |
3850 GFC_STD_F95_DEL | GFC_STD_F95 | GFC_STD_F2003 | GFC_STD_F2008 |
3851 GFC_STD_F2008_TS | GFC_STD_F2008_OBS | GFC_STD_F77 | GFC_STD_F2018 |
3852 GFC_STD_F2018_OBS | GFC_STD_F2018_DEL | GFC_STD_GNU | GFC_STD_LEGACY}.
3853 @item @var{option}[1] @tab Standard-warning flag; prints a warning to
3854 standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}.
3855 @item @var{option}[2] @tab If non zero, enable pedantic checking.
3857 @item @var{option}[3] @tab Unused.
3858 @item @var{option}[4] @tab If non zero, enable backtracing on run-time
3859 errors. Default: off. (Default in the compiler: on.)
3860 Note: Installs a signal handler and requires command-line
3861 initialization using @code{_gfortran_set_args}.
3862 @item @var{option}[5] @tab If non zero, supports signed zeros.
3864 @item @var{option}[6] @tab Enables run-time checking. Possible values
3865 are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2),
3866 GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (16), GFC_RTCHECK_POINTER (32),
3867 GFC_RTCHECK_BITS (64).
3869 @item @var{option}[7] @tab Unused.
3870 @item @var{option}[8] @tab Show a warning when invoking @code{STOP} and
3871 @code{ERROR STOP} if a floating-point exception occurred. Possible values
3872 are (bitwise or-ed) @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3873 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3874 @code{GFC_FPE_UNDERFLOW} (16), @code{GFC_FPE_INEXACT} (32). Default: None (0).
3875 (Default in the compiler: @code{GFC_FPE_INVALID | GFC_FPE_DENORMAL |
3876 GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW}.)
3879 @item @emph{Example}:
3881 /* Use gfortran 4.9 default options. */
3882 static int options[] = @{68, 511, 0, 0, 1, 1, 0, 0, 31@};
3883 _gfortran_set_options (9, &options);
3888 @node _gfortran_set_convert
3889 @subsection @code{_gfortran_set_convert} --- Set endian conversion
3890 @fnindex _gfortran_set_convert
3891 @cindex libgfortran initialization, set_convert
3894 @item @emph{Description}:
3895 @code{_gfortran_set_convert} set the representation of data for
3898 @item @emph{Syntax}:
3899 @code{void _gfortran_set_convert (int conv)}
3901 @item @emph{Arguments}:
3902 @multitable @columnfractions .15 .70
3903 @item @var{conv} @tab Endian conversion, possible values:
3904 GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1),
3905 GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3).
3908 @item @emph{Example}:
3910 int main (int argc, char *argv[])
3912 /* Initialize libgfortran. */
3913 _gfortran_set_args (argc, argv);
3914 _gfortran_set_convert (1);
3921 @node _gfortran_set_record_marker
3922 @subsection @code{_gfortran_set_record_marker} --- Set length of record markers
3923 @fnindex _gfortran_set_record_marker
3924 @cindex libgfortran initialization, set_record_marker
3927 @item @emph{Description}:
3928 @code{_gfortran_set_record_marker} sets the length of record markers
3929 for unformatted files.
3931 @item @emph{Syntax}:
3932 @code{void _gfortran_set_record_marker (int val)}
3934 @item @emph{Arguments}:
3935 @multitable @columnfractions .15 .70
3936 @item @var{val} @tab Length of the record marker; valid values
3937 are 4 and 8. Default is 4.
3940 @item @emph{Example}:
3942 int main (int argc, char *argv[])
3944 /* Initialize libgfortran. */
3945 _gfortran_set_args (argc, argv);
3946 _gfortran_set_record_marker (8);
3953 @node _gfortran_set_fpe
3954 @subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps
3955 @fnindex _gfortran_set_fpe
3956 @cindex libgfortran initialization, set_fpe
3959 @item @emph{Description}:
3960 @code{_gfortran_set_fpe} enables floating point exception traps for
3961 the specified exceptions. On most systems, this will result in a
3962 SIGFPE signal being sent and the program being aborted.
3964 @item @emph{Syntax}:
3965 @code{void _gfortran_set_fpe (int val)}
3967 @item @emph{Arguments}:
3968 @multitable @columnfractions .15 .70
3969 @item @var{option}[0] @tab IEEE exceptions. Possible values are
3970 (bitwise or-ed) zero (0, default) no trapping,
3971 @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3972 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3973 @code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32).
3976 @item @emph{Example}:
3978 int main (int argc, char *argv[])
3980 /* Initialize libgfortran. */
3981 _gfortran_set_args (argc, argv);
3982 /* FPE for invalid operations such as SQRT(-1.0). */
3983 _gfortran_set_fpe (1);
3990 @node _gfortran_set_max_subrecord_length
3991 @subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length
3992 @fnindex _gfortran_set_max_subrecord_length
3993 @cindex libgfortran initialization, set_max_subrecord_length
3996 @item @emph{Description}:
3997 @code{_gfortran_set_max_subrecord_length} set the maximum length
3998 for a subrecord. This option only makes sense for testing and
3999 debugging of unformatted I/O.
4001 @item @emph{Syntax}:
4002 @code{void _gfortran_set_max_subrecord_length (int val)}
4004 @item @emph{Arguments}:
4005 @multitable @columnfractions .15 .70
4006 @item @var{val} @tab the maximum length for a subrecord;
4007 the maximum permitted value is 2147483639, which is also
4011 @item @emph{Example}:
4013 int main (int argc, char *argv[])
4015 /* Initialize libgfortran. */
4016 _gfortran_set_args (argc, argv);
4017 _gfortran_set_max_subrecord_length (8);
4024 @node Naming and argument-passing conventions
4025 @section Naming and argument-passing conventions
4027 This section gives an overview about the naming convention of procedures
4028 and global variables and about the argument passing conventions used by
4029 GNU Fortran. If a C binding has been specified, the naming convention
4030 and some of the argument-passing conventions change. If possible,
4031 mixed-language and mixed-compiler projects should use the better defined
4032 C binding for interoperability. See @pxref{Interoperability with C}.
4035 * Naming conventions::
4036 * Argument passing conventions::
4040 @node Naming conventions
4041 @subsection Naming conventions
4043 According the Fortran standard, valid Fortran names consist of a letter
4044 between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0},
4045 @code{1} to @code{9} and underscores (@code{_}) with the restriction
4046 that names may only start with a letter. As vendor extension, the
4047 dollar sign (@code{$}) is additionally permitted with the option
4048 @option{-fdollar-ok}, but not as first character and only if the
4049 target system supports it.
4051 By default, the procedure name is the lower-cased Fortran name with an
4052 appended underscore (@code{_}); using @option{-fno-underscoring} no
4053 underscore is appended while @code{-fsecond-underscore} appends two
4054 underscores. Depending on the target system and the calling convention,
4055 the procedure might be additionally dressed; for instance, on 32bit
4056 Windows with @code{stdcall}, an at-sign @code{@@} followed by an integer
4057 number is appended. For the changing the calling convention, see
4058 @pxref{GNU Fortran Compiler Directives}.
4060 For common blocks, the same convention is used, i.e. by default an
4061 underscore is appended to the lower-cased Fortran name. Blank commons
4062 have the name @code{__BLNK__}.
4064 For procedures and variables declared in the specification space of a
4065 module, the name is formed by @code{__}, followed by the lower-cased
4066 module name, @code{_MOD_}, and the lower-cased Fortran name. Note that
4067 no underscore is appended.
4070 @node Argument passing conventions
4071 @subsection Argument passing conventions
4073 Subroutines do not return a value (matching C99's @code{void}) while
4074 functions either return a value as specified in the platform ABI or
4075 the result variable is passed as hidden argument to the function and
4076 no result is returned. A hidden result variable is used when the
4077 result variable is an array or of type @code{CHARACTER}.
4079 Arguments are passed according to the platform ABI. In particular,
4080 complex arguments might not be compatible to a struct with two real
4081 components for the real and imaginary part. The argument passing
4082 matches the one of C99's @code{_Complex}. Functions with scalar
4083 complex result variables return their value and do not use a
4084 by-reference argument. Note that with the @option{-ff2c} option,
4085 the argument passing is modified and no longer completely matches
4086 the platform ABI. Some other Fortran compilers use @code{f2c}
4087 semantic by default; this might cause problems with
4090 GNU Fortran passes most arguments by reference, i.e. by passing a
4091 pointer to the data. Note that the compiler might use a temporary
4092 variable into which the actual argument has been copied, if required
4093 semantically (copy-in/copy-out).
4095 For arguments with @code{ALLOCATABLE} and @code{POINTER}
4096 attribute (including procedure pointers), a pointer to the pointer
4097 is passed such that the pointer address can be modified in the
4100 For dummy arguments with the @code{VALUE} attribute: Scalar arguments
4101 of the type @code{INTEGER}, @code{LOGICAL}, @code{REAL} and
4102 @code{COMPLEX} are passed by value according to the platform ABI.
4103 (As vendor extension and not recommended, using @code{%VAL()} in the
4104 call to a procedure has the same effect.) For @code{TYPE(C_PTR)} and
4105 procedure pointers, the pointer itself is passed such that it can be
4106 modified without affecting the caller.
4107 @c FIXME: Document how VALUE is handled for CHARACTER, TYPE,
4108 @c CLASS and arrays, i.e. whether the copy-in is done in the caller
4109 @c or in the callee.
4111 For Boolean (@code{LOGICAL}) arguments, please note that GCC expects
4112 only the integer value 0 and 1. If a GNU Fortran @code{LOGICAL}
4113 variable contains another integer value, the result is undefined.
4114 As some other Fortran compilers use @math{-1} for @code{.TRUE.},
4115 extra care has to be taken -- such as passing the value as
4116 @code{INTEGER}. (The same value restriction also applies to other
4117 front ends of GCC, e.g. to GCC's C99 compiler for @code{_Bool}
4118 or GCC's Ada compiler for @code{Boolean}.)
4120 For arguments of @code{CHARACTER} type, the character length is passed
4121 as a hidden argument at the end of the argument list. For
4122 deferred-length strings, the value is passed by reference, otherwise
4123 by value. The character length has the C type @code{size_t} (or
4124 @code{INTEGER(kind=C_SIZE_T)} in Fortran). Note that this is
4125 different to older versions of the GNU Fortran compiler, where the
4126 type of the hidden character length argument was a C @code{int}. In
4127 order to retain compatibility with older versions, one can e.g. for
4128 the following Fortran procedure
4131 subroutine fstrlen (s, a)
4132 character(len=*) :: s
4135 end subroutine fstrlen
4138 define the corresponding C prototype as follows:
4142 typedef size_t fortran_charlen_t;
4144 typedef int fortran_charlen_t;
4147 void fstrlen_ (char*, int*, fortran_charlen_t);
4150 In order to avoid such compiler-specific details, for new code it is
4151 instead recommended to use the ISO_C_BINDING feature.
4153 Note with C binding, @code{CHARACTER(len=1)} result variables are
4154 returned according to the platform ABI and no hidden length argument
4155 is used for dummy arguments; with @code{VALUE}, those variables are
4158 For @code{OPTIONAL} dummy arguments, an absent argument is denoted
4159 by a NULL pointer, except for scalar dummy arguments of type
4160 @code{INTEGER}, @code{LOGICAL}, @code{REAL} and @code{COMPLEX}
4161 which have the @code{VALUE} attribute. For those, a hidden Boolean
4162 argument (@code{logical(kind=C_bool),value}) is used to indicate
4163 whether the argument is present.
4165 Arguments which are assumed-shape, assumed-rank or deferred-rank
4166 arrays or, with @option{-fcoarray=lib}, allocatable scalar coarrays use
4167 an array descriptor. All other arrays pass the address of the
4168 first element of the array. With @option{-fcoarray=lib}, the token
4169 and the offset belonging to nonallocatable coarrays dummy arguments
4170 are passed as hidden argument along the character length hidden
4171 arguments. The token is an oparque pointer identifying the coarray
4172 and the offset is a passed-by-value integer of kind @code{C_PTRDIFF_T},
4173 denoting the byte offset between the base address of the coarray and
4174 the passed scalar or first element of the passed array.
4176 The arguments are passed in the following order
4178 @item Result variable, when the function result is passed by reference
4179 @item Character length of the function result, if it is a of type
4180 @code{CHARACTER} and no C binding is used
4181 @item The arguments in the order in which they appear in the Fortran
4183 @item The the present status for optional arguments with value attribute,
4184 which are internally passed by value
4185 @item The character length and/or coarray token and offset for the first
4186 argument which is a @code{CHARACTER} or a nonallocatable coarray dummy
4187 argument, followed by the hidden arguments of the next dummy argument
4192 @c ---------------------------------------------------------------------
4193 @c Coarray Programming
4194 @c ---------------------------------------------------------------------
4196 @node Coarray Programming
4197 @chapter Coarray Programming
4201 * Type and enum ABI Documentation::
4202 * Function ABI Documentation::
4206 @node Type and enum ABI Documentation
4207 @section Type and enum ABI Documentation
4212 * caf_deregister_t::
4218 @subsection @code{caf_token_t}
4220 Typedef of type @code{void *} on the compiler side. Can be any data
4221 type on the library side.
4223 @node caf_register_t
4224 @subsection @code{caf_register_t}
4226 Indicates which kind of coarray variable should be registered.
4229 typedef enum caf_register_t {
4230 CAF_REGTYPE_COARRAY_STATIC,
4231 CAF_REGTYPE_COARRAY_ALLOC,
4232 CAF_REGTYPE_LOCK_STATIC,
4233 CAF_REGTYPE_LOCK_ALLOC,
4234 CAF_REGTYPE_CRITICAL,
4235 CAF_REGTYPE_EVENT_STATIC,
4236 CAF_REGTYPE_EVENT_ALLOC,
4237 CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY,
4238 CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY
4243 The values @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and
4244 @code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} are for allocatable components
4245 in derived type coarrays only. The first one sets up the token without
4246 allocating memory for allocatable component. The latter one only allocates the
4247 memory for an allocatable component in a derived type coarray. The token
4248 needs to be setup previously by the REGISTER_ONLY. This allows to have
4249 allocatable components un-allocated on some images. The status whether an
4250 allocatable component is allocated on a remote image can be queried by
4251 @code{_caf_is_present} which used internally by the @code{ALLOCATED}
4254 @node caf_deregister_t
4255 @subsection @code{caf_deregister_t}
4258 typedef enum caf_deregister_t {
4259 CAF_DEREGTYPE_COARRAY_DEREGISTER,
4260 CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY
4265 Allows to specifiy the type of deregistration of a coarray object. The
4266 @code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} flag is only allowed for
4267 allocatable components in derived type coarrays.
4269 @node caf_reference_t
4270 @subsection @code{caf_reference_t}
4272 The structure used for implementing arbitrary reference chains.
4273 A @code{CAF_REFERENCE_T} allows to specify a component reference or any kind
4274 of array reference of any rank supported by gfortran. For array references all
4275 kinds as known by the compiler/Fortran standard are supported indicated by
4279 typedef enum caf_ref_type_t {
4280 /* Reference a component of a derived type, either regular one or an
4281 allocatable or pointer type. For regular ones idx in caf_reference_t is
4284 /* Reference an allocatable array. */
4286 /* Reference a non-allocatable/non-pointer array. I.e., the coarray object
4287 has no array descriptor associated and the addressing is done
4288 completely using the ref. */
4289 CAF_REF_STATIC_ARRAY
4294 typedef enum caf_array_ref_t {
4295 /* No array ref. This terminates the array ref. */
4296 CAF_ARR_REF_NONE = 0,
4297 /* Reference array elements given by a vector. Only for this mode
4298 caf_reference_t.u.a.dim[i].v is valid. */
4300 /* A full array ref (:). */
4302 /* Reference a range on elements given by start, end and stride. */
4304 /* Only a single item is referenced given in the start member. */
4306 /* An array ref of the kind (i:), where i is an arbitrary valid index in the
4307 array. The index i is given in the start member. */
4308 CAF_ARR_REF_OPEN_END,
4309 /* An array ref of the kind (:i), where the lower bound of the array ref
4310 is given by the remote side. The index i is given in the end member. */
4311 CAF_ARR_REF_OPEN_START
4316 /* References to remote components of a derived type. */
4317 typedef struct caf_reference_t {
4318 /* A pointer to the next ref or NULL. */
4319 struct caf_reference_t *next;
4320 /* The type of the reference. */
4321 /* caf_ref_type_t, replaced by int to allow specification in fortran FE. */
4323 /* The size of an item referenced in bytes. I.e. in an array ref this is
4324 the factor to advance the array pointer with to get to the next item.
4325 For component refs this gives just the size of the element referenced. */
4329 /* The offset (in bytes) of the component in the derived type.
4330 Unused for allocatable or pointer components. */
4332 /* The offset (in bytes) to the caf_token associated with this
4333 component. NULL, when not allocatable/pointer ref. */
4334 ptrdiff_t caf_token_offset;
4337 /* The mode of the array ref. See CAF_ARR_REF_*. */
4338 /* caf_array_ref_t, replaced by unsigend char to allow specification in
4340 unsigned char mode[GFC_MAX_DIMENSIONS];
4341 /* The type of a static array. Unset for array's with descriptors. */
4342 int static_array_type;
4343 /* Subscript refs (s) or vector refs (v). */
4346 /* The start and end boundary of the ref and the stride. */
4347 index_type start, end, stride;
4350 /* nvec entries of kind giving the elements to reference. */
4352 /* The number of entries in vector. */
4354 /* The integer kind used for the elements in vector. */
4357 } dim[GFC_MAX_DIMENSIONS];
4363 The references make up a single linked list of reference operations. The
4364 @code{NEXT} member links to the next reference or NULL to indicate the end of
4365 the chain. Component and array refs can be arbitrarly mixed as long as they
4366 comply to the Fortran standard.
4369 The member @code{STATIC_ARRAY_TYPE} is used only when the @code{TYPE} is
4370 @code{CAF_REF_STATIC_ARRAY}. The member gives the type of the data referenced.
4371 Because no array descriptor is available for a descriptor-less array and
4372 type conversion still needs to take place the type is transported here.
4374 At the moment @code{CAF_ARR_REF_VECTOR} is not implemented in the front end for
4375 descriptor-less arrays. The library caf_single has untested support for it.
4378 @subsection @code{caf_team_t}
4380 Opaque pointer to represent a team-handle. This type is a stand-in for the
4381 future implementation of teams. It is about to change without further notice.
4383 @node Function ABI Documentation
4384 @section Function ABI Documentation
4387 * _gfortran_caf_init:: Initialiation function
4388 * _gfortran_caf_finish:: Finalization function
4389 * _gfortran_caf_this_image:: Querying the image number
4390 * _gfortran_caf_num_images:: Querying the maximal number of images
4391 * _gfortran_caf_image_status :: Query the status of an image
4392 * _gfortran_caf_failed_images :: Get an array of the indexes of the failed images
4393 * _gfortran_caf_stopped_images :: Get an array of the indexes of the stopped images
4394 * _gfortran_caf_register:: Registering coarrays
4395 * _gfortran_caf_deregister:: Deregistering coarrays
4396 * _gfortran_caf_is_present:: Query whether an allocatable or pointer component in a derived type coarray is allocated
4397 * _gfortran_caf_send:: Sending data from a local image to a remote image
4398 * _gfortran_caf_get:: Getting data from a remote image
4399 * _gfortran_caf_sendget:: Sending data between remote images
4400 * _gfortran_caf_send_by_ref:: Sending data from a local image to a remote image using enhanced references
4401 * _gfortran_caf_get_by_ref:: Getting data from a remote image using enhanced references
4402 * _gfortran_caf_sendget_by_ref:: Sending data between remote images using enhanced references
4403 * _gfortran_caf_lock:: Locking a lock variable
4404 * _gfortran_caf_unlock:: Unlocking a lock variable
4405 * _gfortran_caf_event_post:: Post an event
4406 * _gfortran_caf_event_wait:: Wait that an event occurred
4407 * _gfortran_caf_event_query:: Query event count
4408 * _gfortran_caf_sync_all:: All-image barrier
4409 * _gfortran_caf_sync_images:: Barrier for selected images
4410 * _gfortran_caf_sync_memory:: Wait for completion of segment-memory operations
4411 * _gfortran_caf_error_stop:: Error termination with exit code
4412 * _gfortran_caf_error_stop_str:: Error termination with string
4413 * _gfortran_caf_fail_image :: Mark the image failed and end its execution
4414 * _gfortran_caf_atomic_define:: Atomic variable assignment
4415 * _gfortran_caf_atomic_ref:: Atomic variable reference
4416 * _gfortran_caf_atomic_cas:: Atomic compare and swap
4417 * _gfortran_caf_atomic_op:: Atomic operation
4418 * _gfortran_caf_co_broadcast:: Sending data to all images
4419 * _gfortran_caf_co_max:: Collective maximum reduction
4420 * _gfortran_caf_co_min:: Collective minimum reduction
4421 * _gfortran_caf_co_sum:: Collective summing reduction
4422 * _gfortran_caf_co_reduce:: Generic collective reduction
4426 @node _gfortran_caf_init
4427 @subsection @code{_gfortran_caf_init} --- Initialiation function
4428 @cindex Coarray, _gfortran_caf_init
4431 @item @emph{Description}:
4432 This function is called at startup of the program before the Fortran main
4433 program, if the latter has been compiled with @option{-fcoarray=lib}.
4434 It takes as arguments the command-line arguments of the program. It is
4435 permitted to pass two @code{NULL} pointers as argument; if non-@code{NULL},
4436 the library is permitted to modify the arguments.
4438 @item @emph{Syntax}:
4439 @code{void _gfortran_caf_init (int *argc, char ***argv)}
4441 @item @emph{Arguments}:
4442 @multitable @columnfractions .15 .70
4443 @item @var{argc} @tab intent(inout) An integer pointer with the number of
4444 arguments passed to the program or @code{NULL}.
4445 @item @var{argv} @tab intent(inout) A pointer to an array of strings with the
4446 command-line arguments or @code{NULL}.
4450 The function is modelled after the initialization function of the Message
4451 Passing Interface (MPI) specification. Due to the way coarray registration
4452 works, it might not be the first call to the library. If the main program is
4453 not written in Fortran and only a library uses coarrays, it can happen that
4454 this function is never called. Therefore, it is recommended that the library
4455 does not rely on the passed arguments and whether the call has been done.
4459 @node _gfortran_caf_finish
4460 @subsection @code{_gfortran_caf_finish} --- Finalization function
4461 @cindex Coarray, _gfortran_caf_finish
4464 @item @emph{Description}:
4465 This function is called at the end of the Fortran main program, if it has
4466 been compiled with the @option{-fcoarray=lib} option.
4468 @item @emph{Syntax}:
4469 @code{void _gfortran_caf_finish (void)}
4472 For non-Fortran programs, it is recommended to call the function at the end
4473 of the main program. To ensure that the shutdown is also performed for
4474 programs where this function is not explicitly invoked, for instance
4475 non-Fortran programs or calls to the system's exit() function, the library
4476 can use a destructor function. Note that programs can also be terminated
4477 using the STOP and ERROR STOP statements; those use different library calls.
4481 @node _gfortran_caf_this_image
4482 @subsection @code{_gfortran_caf_this_image} --- Querying the image number
4483 @cindex Coarray, _gfortran_caf_this_image
4486 @item @emph{Description}:
4487 This function returns the current image number, which is a positive number.
4489 @item @emph{Syntax}:
4490 @code{int _gfortran_caf_this_image (int distance)}
4492 @item @emph{Arguments}:
4493 @multitable @columnfractions .15 .70
4494 @item @var{distance} @tab As specified for the @code{this_image} intrinsic
4495 in TS18508. Shall be a non-negative number.
4499 If the Fortran intrinsic @code{this_image} is invoked without an argument, which
4500 is the only permitted form in Fortran 2008, GCC passes @code{0} as
4505 @node _gfortran_caf_num_images
4506 @subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images
4507 @cindex Coarray, _gfortran_caf_num_images
4510 @item @emph{Description}:
4511 This function returns the number of images in the current team, if
4512 @var{distance} is 0 or the number of images in the parent team at the specified
4513 distance. If failed is -1, the function returns the number of all images at
4514 the specified distance; if it is 0, the function returns the number of
4515 nonfailed images, and if it is 1, it returns the number of failed images.
4517 @item @emph{Syntax}:
4518 @code{int _gfortran_caf_num_images(int distance, int failed)}
4520 @item @emph{Arguments}:
4521 @multitable @columnfractions .15 .70
4522 @item @var{distance} @tab the distance from this image to the ancestor.
4524 @item @var{failed} @tab shall be -1, 0, or 1
4528 This function follows TS18508. If the num_image intrinsic has no arguments,
4529 then the compiler passes @code{distance=0} and @code{failed=-1} to the function.
4533 @node _gfortran_caf_image_status
4534 @subsection @code{_gfortran_caf_image_status} --- Query the status of an image
4535 @cindex Coarray, _gfortran_caf_image_status
4538 @item @emph{Description}:
4539 Get the status of the image given by the id @var{image} of the team given by
4540 @var{team}. Valid results are zero, for image is ok, @code{STAT_STOPPED_IMAGE}
4541 from the ISO_FORTRAN_ENV module to indicate that the image has been stopped and
4542 @code{STAT_FAILED_IMAGE} also from ISO_FORTRAN_ENV to indicate that the image
4543 has executed a @code{FAIL IMAGE} statement.
4545 @item @emph{Syntax}:
4546 @code{int _gfortran_caf_image_status (int image, caf_team_t * team)}
4548 @item @emph{Arguments}:
4549 @multitable @columnfractions .15 .70
4550 @item @var{image} @tab the positive scalar id of the image in the current TEAM.
4551 @item @var{team} @tab optional; team on the which the inquiry is to be
4556 This function follows TS18508. Because team-functionality is not yet
4557 implemented a null-pointer is passed for the @var{team} argument at the moment.
4561 @node _gfortran_caf_failed_images
4562 @subsection @code{_gfortran_caf_failed_images} --- Get an array of the indexes of the failed images
4563 @cindex Coarray, _gfortran_caf_failed_images
4566 @item @emph{Description}:
4567 Get an array of image indexes in the current @var{team} that have failed. The
4568 array is sorted ascendingly. When @var{team} is not provided the current team
4569 is to be used. When @var{kind} is provided then the resulting array is of that
4570 integer kind else it is of default integer kind. The returns an unallocated
4571 size zero array when no images have failed.
4573 @item @emph{Syntax}:
4574 @code{int _gfortran_caf_failed_images (caf_team_t * team, int * kind)}
4576 @item @emph{Arguments}:
4577 @multitable @columnfractions .15 .70
4578 @item @var{team} @tab optional; team on the which the inquiry is to be
4580 @item @var{image} @tab optional; the kind of the resulting integer array.
4584 This function follows TS18508. Because team-functionality is not yet
4585 implemented a null-pointer is passed for the @var{team} argument at the moment.
4589 @node _gfortran_caf_stopped_images
4590 @subsection @code{_gfortran_caf_stopped_images} --- Get an array of the indexes of the stopped images
4591 @cindex Coarray, _gfortran_caf_stopped_images
4594 @item @emph{Description}:
4595 Get an array of image indexes in the current @var{team} that have stopped. The
4596 array is sorted ascendingly. When @var{team} is not provided the current team
4597 is to be used. When @var{kind} is provided then the resulting array is of that
4598 integer kind else it is of default integer kind. The returns an unallocated
4599 size zero array when no images have failed.
4601 @item @emph{Syntax}:
4602 @code{int _gfortran_caf_stopped_images (caf_team_t * team, int * kind)}
4604 @item @emph{Arguments}:
4605 @multitable @columnfractions .15 .70
4606 @item @var{team} @tab optional; team on the which the inquiry is to be
4608 @item @var{image} @tab optional; the kind of the resulting integer array.
4612 This function follows TS18508. Because team-functionality is not yet
4613 implemented a null-pointer is passed for the @var{team} argument at the moment.
4617 @node _gfortran_caf_register
4618 @subsection @code{_gfortran_caf_register} --- Registering coarrays
4619 @cindex Coarray, _gfortran_caf_register
4622 @item @emph{Description}:
4623 Registers memory for a coarray and creates a token to identify the coarray. The
4624 routine is called for both coarrays with @code{SAVE} attribute and using an
4625 explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a
4626 @code{NULL} pointer, the function shall abort with printing an error message
4627 and starting the error termination. If no error occurs and @var{STAT} is
4628 present, it shall be set to zero. Otherwise, it shall be set to a positive
4629 value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing
4630 the failure. The routine shall register the memory provided in the
4631 @code{DATA}-component of the array descriptor @var{DESC}, when that component
4632 is non-@code{NULL}, else it shall allocate sufficient memory and provide a
4633 pointer to it in the @code{DATA}-component of @var{DESC}. The array descriptor
4634 has rank zero, when a scalar object is to be registered and the array
4635 descriptor may be invalid after the call to @code{_gfortran_caf_register}.
4636 When an array is to be allocated the descriptor persists.
4638 For @code{CAF_REGTYPE_COARRAY_STATIC} and @code{CAF_REGTYPE_COARRAY_ALLOC},
4639 the passed size is the byte size requested. For @code{CAF_REGTYPE_LOCK_STATIC},
4640 @code{CAF_REGTYPE_LOCK_ALLOC} and @code{CAF_REGTYPE_CRITICAL} it is the array
4641 size or one for a scalar.
4643 When @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} is used, then only a token
4644 for an allocatable or pointer component is created. The @code{SIZE} parameter
4645 is not used then. On the contrary when
4646 @code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} is specified, then the
4647 @var{token} needs to be registered by a previous call with regtype
4648 @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and either the memory specified
4649 in the @var{DESC}'s data-ptr is registered or allocate when the data-ptr is
4652 @item @emph{Syntax}:
4653 @code{void caf_register (size_t size, caf_register_t type, caf_token_t *token,
4654 gfc_descriptor_t *desc, int *stat, char *errmsg, size_t errmsg_len)}
4656 @item @emph{Arguments}:
4657 @multitable @columnfractions .15 .70
4658 @item @var{size} @tab For normal coarrays, the byte size of the coarray to be
4659 allocated; for lock types and event types, the number of elements.
4660 @item @var{type} @tab one of the caf_register_t types.
4661 @item @var{token} @tab intent(out) An opaque pointer identifying the coarray.
4662 @item @var{desc} @tab intent(inout) The (pseudo) array descriptor.
4663 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
4665 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4666 an error message; may be @code{NULL}
4667 @item @var{errmsg_len} @tab the buffer size of errmsg.
4671 Nonallocatable coarrays have to be registered prior use from remote images.
4672 In order to guarantee this, they have to be registered before the main
4673 program. This can be achieved by creating constructor functions. That is what
4674 GCC does such that also for nonallocatable coarrays the memory is allocated and
4675 no static memory is used. The token permits to identify the coarray; to the
4676 processor, the token is a nonaliasing pointer. The library can, for instance,
4677 store the base address of the coarray in the token, some handle or a more
4678 complicated struct. The library may also store the array descriptor
4679 @var{DESC} when its rank is non-zero.
4681 For lock types, the value shall only be used for checking the allocation
4682 status. Note that for critical blocks, the locking is only required on one
4683 image; in the locking statement, the processor shall always pass an
4684 image index of one for critical-block lock variables
4685 (@code{CAF_REGTYPE_CRITICAL}). For lock types and critical-block variables,
4686 the initial value shall be unlocked (or, respecitively, not in critical
4687 section) such as the value false; for event types, the initial state should
4688 be no event, e.g. zero.
4692 @node _gfortran_caf_deregister
4693 @subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays
4694 @cindex Coarray, _gfortran_caf_deregister
4697 @item @emph{Description}:
4698 Called to free or deregister the memory of a coarray; the processor calls this
4699 function for automatic and explicit deallocation. In case of an error, this
4700 function shall fail with an error message, unless the @var{STAT} variable is
4701 not null. The library is only expected to free memory it allocated itself
4702 during a call to @code{_gfortran_caf_register}.
4704 @item @emph{Syntax}:
4705 @code{void caf_deregister (caf_token_t *token, caf_deregister_t type,
4706 int *stat, char *errmsg, size_t errmsg_len)}
4708 @item @emph{Arguments}:
4709 @multitable @columnfractions .15 .70
4710 @item @var{token} @tab the token to free.
4711 @item @var{type} @tab the type of action to take for the coarray. A
4712 @code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} is allowed only for allocatable or
4713 pointer components of derived type coarrays. The action only deallocates the
4714 local memory without deleting the token.
4715 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
4716 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set
4717 to an error message; may be NULL
4718 @item @var{errmsg_len} @tab the buffer size of errmsg.
4722 For nonalloatable coarrays this function is never called. If a cleanup is
4723 required, it has to be handled via the finish, stop and error stop functions,
4724 and via destructors.
4728 @node _gfortran_caf_is_present
4729 @subsection @code{_gfortran_caf_is_present} --- Query whether an allocatable or pointer component in a derived type coarray is allocated
4730 @cindex Coarray, _gfortran_caf_is_present
4733 @item @emph{Description}:
4734 Used to query the coarray library whether an allocatable component in a derived
4735 type coarray is allocated on a remote image.
4737 @item @emph{Syntax}:
4738 @code{void _gfortran_caf_is_present (caf_token_t token, int image_index,
4739 gfc_reference_t *ref)}
4741 @item @emph{Arguments}:
4742 @multitable @columnfractions .15 .70
4743 @item @var{token} @tab An opaque pointer identifying the coarray.
4744 @item @var{image_index} @tab The ID of the remote image; must be a positive
4746 @item @var{ref} @tab A chain of references to address the allocatable or
4747 pointer component in the derived type coarray. The object reference needs to be
4748 a scalar or a full array reference, respectively.
4753 @node _gfortran_caf_send
4754 @subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image
4755 @cindex Coarray, _gfortran_caf_send
4758 @item @emph{Description}:
4759 Called to send a scalar, an array section or a whole array from a local
4760 to a remote image identified by the image_index.
4762 @item @emph{Syntax}:
4763 @code{void _gfortran_caf_send (caf_token_t token, size_t offset,
4764 int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
4765 gfc_descriptor_t *src, int dst_kind, int src_kind, bool may_require_tmp,
4768 @item @emph{Arguments}:
4769 @multitable @columnfractions .15 .70
4770 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4771 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
4772 shifted compared to the base address of the coarray.
4773 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4775 @item @var{dest} @tab intent(in) Array descriptor for the remote image for the
4776 bounds and the size. The @code{base_addr} shall not be accessed.
4777 @item @var{dst_vector} @tab intent(in) If not NULL, it contains the vector
4778 subscript of the destination array; the values are relative to the dimension
4779 triplet of the dest argument.
4780 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4781 transferred to the remote image
4782 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4783 @item @var{src_kind} @tab intent(in) Kind of the source argument
4784 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4785 it is known at compile time that the @var{dest} and @var{src} either cannot
4786 overlap or overlap (fully or partially) such that walking @var{src} and
4787 @var{dest} in element wise element order (honoring the stride value) will not
4788 lead to wrong results. Otherwise, the value is @code{true}.
4789 @item @var{stat} @tab intent(out) when non-NULL give the result of the
4790 operation, i.e., zero on success and non-zero on error. When NULL and an error
4791 occurs, then an error message is printed and the program is terminated.
4795 It is permitted to have @var{image_index} equal the current image; the memory
4796 of the send-to and the send-from might (partially) overlap in that case. The
4797 implementation has to take care that it handles this case, e.g. using
4798 @code{memmove} which handles (partially) overlapping memory. If
4799 @var{may_require_tmp} is true, the library might additionally create a
4800 temporary variable, unless additional checks show that this is not required
4801 (e.g. because walking backward is possible or because both arrays are
4802 contiguous and @code{memmove} takes care of overlap issues).
4804 Note that the assignment of a scalar to an array is permitted. In addition,
4805 the library has to handle numeric-type conversion and for strings, padding
4806 and different character kinds.
4810 @node _gfortran_caf_get
4811 @subsection @code{_gfortran_caf_get} --- Getting data from a remote image
4812 @cindex Coarray, _gfortran_caf_get
4815 @item @emph{Description}:
4816 Called to get an array section or a whole array from a remote,
4817 image identified by the image_index.
4819 @item @emph{Syntax}:
4820 @code{void _gfortran_caf_get (caf_token_t token, size_t offset,
4821 int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector,
4822 gfc_descriptor_t *dest, int src_kind, int dst_kind, bool may_require_tmp,
4825 @item @emph{Arguments}:
4826 @multitable @columnfractions .15 .70
4827 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4828 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
4829 shifted compared to the base address of the coarray.
4830 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4832 @item @var{dest} @tab intent(out) Array descriptor of the local array to store
4833 the data retrieved from the remote image
4834 @item @var{src} @tab intent(in) Array descriptor for the remote image for the
4835 bounds and the size. The @code{base_addr} shall not be accessed.
4836 @item @var{src_vector} @tab intent(in) If not NULL, it contains the vector
4837 subscript of the source array; the values are relative to the dimension
4838 triplet of the @var{src} argument.
4839 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4840 @item @var{src_kind} @tab intent(in) Kind of the source argument
4841 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4842 it is known at compile time that the @var{dest} and @var{src} either cannot
4843 overlap or overlap (fully or partially) such that walking @var{src} and
4844 @var{dest} in element wise element order (honoring the stride value) will not
4845 lead to wrong results. Otherwise, the value is @code{true}.
4846 @item @var{stat} @tab intent(out) When non-NULL give the result of the
4847 operation, i.e., zero on success and non-zero on error. When NULL and an error
4848 occurs, then an error message is printed and the program is terminated.
4852 It is permitted to have @var{image_index} equal the current image; the memory of
4853 the send-to and the send-from might (partially) overlap in that case. The
4854 implementation has to take care that it handles this case, e.g. using
4855 @code{memmove} which handles (partially) overlapping memory. If
4856 @var{may_require_tmp} is true, the library might additionally create a
4857 temporary variable, unless additional checks show that this is not required
4858 (e.g. because walking backward is possible or because both arrays are
4859 contiguous and @code{memmove} takes care of overlap issues).
4861 Note that the library has to handle numeric-type conversion and for strings,
4862 padding and different character kinds.
4866 @node _gfortran_caf_sendget
4867 @subsection @code{_gfortran_caf_sendget} --- Sending data between remote images
4868 @cindex Coarray, _gfortran_caf_sendget
4871 @item @emph{Description}:
4872 Called to send a scalar, an array section or a whole array from a remote image
4873 identified by the @var{src_image_index} to a remote image identified by the
4874 @var{dst_image_index}.
4876 @item @emph{Syntax}:
4877 @code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset,
4878 int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
4879 caf_token_t src_token, size_t src_offset, int src_image_index,
4880 gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind,
4881 bool may_require_tmp, int *stat)}
4883 @item @emph{Arguments}:
4884 @multitable @columnfractions .15 .70
4885 @item @var{dst_token} @tab intent(in) An opaque pointer identifying the
4886 destination coarray.
4887 @item @var{dst_offset} @tab intent(in) By which amount of bytes the actual data
4888 is shifted compared to the base address of the destination coarray.
4889 @item @var{dst_image_index} @tab intent(in) The ID of the destination remote
4890 image; must be a positive number.
4891 @item @var{dest} @tab intent(in) Array descriptor for the destination
4892 remote image for the bounds and the size. The @code{base_addr} shall not be
4894 @item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
4895 subscript of the destination array; the values are relative to the dimension
4896 triplet of the @var{dest} argument.
4897 @item @var{src_token} @tab intent(in) An opaque pointer identifying the source
4899 @item @var{src_offset} @tab intent(in) By which amount of bytes the actual data
4900 is shifted compared to the base address of the source coarray.
4901 @item @var{src_image_index} @tab intent(in) The ID of the source remote image;
4902 must be a positive number.
4903 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4904 transferred to the remote image.
4905 @item @var{src_vector} @tab intent(in) Array descriptor of the local array to
4906 be transferred to the remote image
4907 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4908 @item @var{src_kind} @tab intent(in) Kind of the source argument
4909 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4910 it is known at compile time that the @var{dest} and @var{src} either cannot
4911 overlap or overlap (fully or partially) such that walking @var{src} and
4912 @var{dest} in element wise element order (honoring the stride value) will not
4913 lead to wrong results. Otherwise, the value is @code{true}.
4914 @item @var{stat} @tab intent(out) when non-NULL give the result of the
4915 operation, i.e., zero on success and non-zero on error. When NULL and an error
4916 occurs, then an error message is printed and the program is terminated.
4920 It is permitted to have the same image index for both @var{src_image_index} and
4921 @var{dst_image_index}; the memory of the send-to and the send-from might
4922 (partially) overlap in that case. The implementation has to take care that it
4923 handles this case, e.g. using @code{memmove} which handles (partially)
4924 overlapping memory. If @var{may_require_tmp} is true, the library
4925 might additionally create a temporary variable, unless additional checks show
4926 that this is not required (e.g. because walking backward is possible or because
4927 both arrays are contiguous and @code{memmove} takes care of overlap issues).
4929 Note that the assignment of a scalar to an array is permitted. In addition,
4930 the library has to handle numeric-type conversion and for strings, padding and
4931 different character kinds.
4934 @node _gfortran_caf_send_by_ref
4935 @subsection @code{_gfortran_caf_send_by_ref} --- Sending data from a local image to a remote image with enhanced referencing options
4936 @cindex Coarray, _gfortran_caf_send_by_ref
4939 @item @emph{Description}:
4940 Called to send a scalar, an array section or a whole array from a local to a
4941 remote image identified by the @var{image_index}.
4943 @item @emph{Syntax}:
4944 @code{void _gfortran_caf_send_by_ref (caf_token_t token, int image_index,
4945 gfc_descriptor_t *src, caf_reference_t *refs, int dst_kind, int src_kind,
4946 bool may_require_tmp, bool dst_reallocatable, int *stat, int dst_type)}
4948 @item @emph{Arguments}:
4949 @multitable @columnfractions .15 .70
4950 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4951 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4953 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4954 transferred to the remote image
4955 @item @var{refs} @tab intent(in) The references on the remote array to store
4956 the data given by src. Guaranteed to have at least one entry.
4957 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4958 @item @var{src_kind} @tab intent(in) Kind of the source argument
4959 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4960 it is known at compile time that the @var{dest} and @var{src} either cannot
4961 overlap or overlap (fully or partially) such that walking @var{src} and
4962 @var{dest} in element wise element order (honoring the stride value) will not
4963 lead to wrong results. Otherwise, the value is @code{true}.
4964 @item @var{dst_reallocatable} @tab intent(in) Set when the destination is of
4965 allocatable or pointer type and the refs will allow reallocation, i.e., the ref
4966 is a full array or component ref.
4967 @item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the
4968 operation, i.e., zero on success and non-zero on error. When @code{NULL} and
4969 an error occurs, then an error message is printed and the program is terminated.
4970 @item @var{dst_type} @tab intent(in) Give the type of the destination. When
4971 the destination is not an array, than the precise type, e.g. of a component in
4972 a derived type, is not known, but provided here.
4976 It is permitted to have @var{image_index} equal the current image; the memory of
4977 the send-to and the send-from might (partially) overlap in that case. The
4978 implementation has to take care that it handles this case, e.g. using
4979 @code{memmove} which handles (partially) overlapping memory. If
4980 @var{may_require_tmp} is true, the library might additionally create a
4981 temporary variable, unless additional checks show that this is not required
4982 (e.g. because walking backward is possible or because both arrays are
4983 contiguous and @code{memmove} takes care of overlap issues).
4985 Note that the assignment of a scalar to an array is permitted. In addition,
4986 the library has to handle numeric-type conversion and for strings, padding
4987 and different character kinds.
4989 Because of the more complicated references possible some operations may be
4990 unsupported by certain libraries. The library is expected to issue a precise
4991 error message why the operation is not permitted.
4995 @node _gfortran_caf_get_by_ref
4996 @subsection @code{_gfortran_caf_get_by_ref} --- Getting data from a remote image using enhanced references
4997 @cindex Coarray, _gfortran_caf_get_by_ref
5000 @item @emph{Description}:
5001 Called to get a scalar, an array section or a whole array from a remote image
5002 identified by the @var{image_index}.
5004 @item @emph{Syntax}:
5005 @code{void _gfortran_caf_get_by_ref (caf_token_t token, int image_index,
5006 caf_reference_t *refs, gfc_descriptor_t *dst, int dst_kind, int src_kind,
5007 bool may_require_tmp, bool dst_reallocatable, int *stat, int src_type)}
5009 @item @emph{Arguments}:
5010 @multitable @columnfractions .15 .70
5011 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5012 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5014 @item @var{refs} @tab intent(in) The references to apply to the remote structure
5016 @item @var{dst} @tab intent(in) Array descriptor of the local array to store
5017 the data transferred from the remote image. May be reallocated where needed
5018 and when @var{DST_REALLOCATABLE} allows it.
5019 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
5020 @item @var{src_kind} @tab intent(in) Kind of the source argument
5021 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
5022 it is known at compile time that the @var{dest} and @var{src} either cannot
5023 overlap or overlap (fully or partially) such that walking @var{src} and
5024 @var{dest} in element wise element order (honoring the stride value) will not
5025 lead to wrong results. Otherwise, the value is @code{true}.
5026 @item @var{dst_reallocatable} @tab intent(in) Set when @var{DST} is of
5027 allocatable or pointer type and its refs allow reallocation, i.e., the full
5028 array or a component is referenced.
5029 @item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the
5030 operation, i.e., zero on success and non-zero on error. When @code{NULL} and an
5031 error occurs, then an error message is printed and the program is terminated.
5032 @item @var{src_type} @tab intent(in) Give the type of the source. When the
5033 source is not an array, than the precise type, e.g. of a component in a
5034 derived type, is not known, but provided here.
5038 It is permitted to have @code{image_index} equal the current image; the memory
5039 of the send-to and the send-from might (partially) overlap in that case. The
5040 implementation has to take care that it handles this case, e.g. using
5041 @code{memmove} which handles (partially) overlapping memory. If
5042 @var{may_require_tmp} is true, the library might additionally create a
5043 temporary variable, unless additional checks show that this is not required
5044 (e.g. because walking backward is possible or because both arrays are
5045 contiguous and @code{memmove} takes care of overlap issues).
5047 Note that the library has to handle numeric-type conversion and for strings,
5048 padding and different character kinds.
5050 Because of the more complicated references possible some operations may be
5051 unsupported by certain libraries. The library is expected to issue a precise
5052 error message why the operation is not permitted.
5056 @node _gfortran_caf_sendget_by_ref
5057 @subsection @code{_gfortran_caf_sendget_by_ref} --- Sending data between remote images using enhanced references on both sides
5058 @cindex Coarray, _gfortran_caf_sendget_by_ref
5061 @item @emph{Description}:
5062 Called to send a scalar, an array section or a whole array from a remote image
5063 identified by the @var{src_image_index} to a remote image identified by the
5064 @var{dst_image_index}.
5066 @item @emph{Syntax}:
5067 @code{void _gfortran_caf_sendget_by_ref (caf_token_t dst_token,
5068 int dst_image_index, caf_reference_t *dst_refs,
5069 caf_token_t src_token, int src_image_index, caf_reference_t *src_refs,
5070 int dst_kind, int src_kind, bool may_require_tmp, int *dst_stat,
5071 int *src_stat, int dst_type, int src_type)}
5073 @item @emph{Arguments}:
5074 @multitable @columnfractions .15 .70
5075 @item @var{dst_token} @tab intent(in) An opaque pointer identifying the
5076 destination coarray.
5077 @item @var{dst_image_index} @tab intent(in) The ID of the destination remote
5078 image; must be a positive number.
5079 @item @var{dst_refs} @tab intent(in) The references on the remote array to store
5080 the data given by the source. Guaranteed to have at least one entry.
5081 @item @var{src_token} @tab intent(in) An opaque pointer identifying the source
5083 @item @var{src_image_index} @tab intent(in) The ID of the source remote image;
5084 must be a positive number.
5085 @item @var{src_refs} @tab intent(in) The references to apply to the remote
5086 structure to get the data.
5087 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
5088 @item @var{src_kind} @tab intent(in) Kind of the source argument
5089 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
5090 it is known at compile time that the @var{dest} and @var{src} either cannot
5091 overlap or overlap (fully or partially) such that walking @var{src} and
5092 @var{dest} in element wise element order (honoring the stride value) will not
5093 lead to wrong results. Otherwise, the value is @code{true}.
5094 @item @var{dst_stat} @tab intent(out) when non-@code{NULL} give the result of
5095 the send-operation, i.e., zero on success and non-zero on error. When
5096 @code{NULL} and an error occurs, then an error message is printed and the
5097 program is terminated.
5098 @item @var{src_stat} @tab intent(out) When non-@code{NULL} give the result of
5099 the get-operation, i.e., zero on success and non-zero on error. When
5100 @code{NULL} and an error occurs, then an error message is printed and the
5101 program is terminated.
5102 @item @var{dst_type} @tab intent(in) Give the type of the destination. When
5103 the destination is not an array, than the precise type, e.g. of a component in
5104 a derived type, is not known, but provided here.
5105 @item @var{src_type} @tab intent(in) Give the type of the source. When the
5106 source is not an array, than the precise type, e.g. of a component in a
5107 derived type, is not known, but provided here.
5111 It is permitted to have the same image index for both @var{src_image_index} and
5112 @var{dst_image_index}; the memory of the send-to and the send-from might
5113 (partially) overlap in that case. The implementation has to take care that it
5114 handles this case, e.g. using @code{memmove} which handles (partially)
5115 overlapping memory. If @var{may_require_tmp} is true, the library
5116 might additionally create a temporary variable, unless additional checks show
5117 that this is not required (e.g. because walking backward is possible or because
5118 both arrays are contiguous and @code{memmove} takes care of overlap issues).
5120 Note that the assignment of a scalar to an array is permitted. In addition,
5121 the library has to handle numeric-type conversion and for strings, padding and
5122 different character kinds.
5124 Because of the more complicated references possible some operations may be
5125 unsupported by certain libraries. The library is expected to issue a precise
5126 error message why the operation is not permitted.
5130 @node _gfortran_caf_lock
5131 @subsection @code{_gfortran_caf_lock} --- Locking a lock variable
5132 @cindex Coarray, _gfortran_caf_lock
5135 @item @emph{Description}:
5136 Acquire a lock on the given image on a scalar locking variable or for the
5137 given array element for an array-valued variable. If the @var{aquired_lock}
5138 is @code{NULL}, the function returns after having obtained the lock. If it is
5139 non-@code{NULL}, then @var{acquired_lock} is assigned the value true (one) when
5140 the lock could be obtained and false (zero) otherwise. Locking a lock variable
5141 which has already been locked by the same image is an error.
5143 @item @emph{Syntax}:
5144 @code{void _gfortran_caf_lock (caf_token_t token, size_t index, int image_index,
5145 int *aquired_lock, int *stat, char *errmsg, size_t errmsg_len)}
5147 @item @emph{Arguments}:
5148 @multitable @columnfractions .15 .70
5149 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5150 @item @var{index} @tab intent(in) Array index; first array index is 0. For
5151 scalars, it is always 0.
5152 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5154 @item @var{aquired_lock} @tab intent(out) If not NULL, it returns whether lock
5156 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
5157 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5158 an error message; may be NULL.
5159 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5163 This function is also called for critical blocks; for those, the array index
5164 is always zero and the image index is one. Libraries are permitted to use other
5165 images for critical-block locking variables.
5168 @node _gfortran_caf_unlock
5169 @subsection @code{_gfortran_caf_lock} --- Unlocking a lock variable
5170 @cindex Coarray, _gfortran_caf_unlock
5173 @item @emph{Description}:
5174 Release a lock on the given image on a scalar locking variable or for the
5175 given array element for an array-valued variable. Unlocking a lock variable
5176 which is unlocked or has been locked by a different image is an error.
5178 @item @emph{Syntax}:
5179 @code{void _gfortran_caf_unlock (caf_token_t token, size_t index, int image_index,
5180 int *stat, char *errmsg, size_t errmsg_len)}
5182 @item @emph{Arguments}:
5183 @multitable @columnfractions .15 .70
5184 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5185 @item @var{index} @tab intent(in) Array index; first array index is 0. For
5186 scalars, it is always 0.
5187 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5189 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
5191 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5192 an error message; may be NULL.
5193 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5197 This function is also called for critical block; for those, the array index
5198 is always zero and the image index is one. Libraries are permitted to use other
5199 images for critical-block locking variables.
5202 @node _gfortran_caf_event_post
5203 @subsection @code{_gfortran_caf_event_post} --- Post an event
5204 @cindex Coarray, _gfortran_caf_event_post
5207 @item @emph{Description}:
5208 Increment the event count of the specified event variable.
5210 @item @emph{Syntax}:
5211 @code{void _gfortran_caf_event_post (caf_token_t token, size_t index,
5212 int image_index, int *stat, char *errmsg, size_t errmsg_len)}
5214 @item @emph{Arguments}:
5215 @multitable @columnfractions .15 .70
5216 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5217 @item @var{index} @tab intent(in) Array index; first array index is 0. For
5218 scalars, it is always 0.
5219 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5220 positive number; zero indicates the current image, when accessed noncoindexed.
5221 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
5222 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5223 an error message; may be NULL.
5224 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5228 This acts like an atomic add of one to the remote image's event variable.
5229 The statement is an image-control statement but does not imply sync memory.
5230 Still, all preceeding push communications of this image to the specified
5231 remote image have to be completed before @code{event_wait} on the remote
5237 @node _gfortran_caf_event_wait
5238 @subsection @code{_gfortran_caf_event_wait} --- Wait that an event occurred
5239 @cindex Coarray, _gfortran_caf_event_wait
5242 @item @emph{Description}:
5243 Wait until the event count has reached at least the specified
5244 @var{until_count}; if so, atomically decrement the event variable by this
5247 @item @emph{Syntax}:
5248 @code{void _gfortran_caf_event_wait (caf_token_t token, size_t index,
5249 int until_count, int *stat, char *errmsg, size_t errmsg_len)}
5251 @item @emph{Arguments}:
5252 @multitable @columnfractions .15 .70
5253 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5254 @item @var{index} @tab intent(in) Array index; first array index is 0. For
5255 scalars, it is always 0.
5256 @item @var{until_count} @tab intent(in) The number of events which have to be
5257 available before the function returns.
5258 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
5259 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5260 an error message; may be NULL.
5261 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5265 This function only operates on a local coarray. It acts like a loop checking
5266 atomically the value of the event variable, breaking if the value is greater
5267 or equal the requested number of counts. Before the function returns, the
5268 event variable has to be decremented by the requested @var{until_count} value.
5269 A possible implementation would be a busy loop for a certain number of spins
5270 (possibly depending on the number of threads relative to the number of available
5271 cores) followed by another waiting strategy such as a sleeping wait (possibly
5272 with an increasing number of sleep time) or, if possible, a futex wait.
5274 The statement is an image-control statement but does not imply sync memory.
5275 Still, all preceeding push communications of this image to the specified
5276 remote image have to be completed before @code{event_wait} on the remote
5282 @node _gfortran_caf_event_query
5283 @subsection @code{_gfortran_caf_event_query} --- Query event count
5284 @cindex Coarray, _gfortran_caf_event_query
5287 @item @emph{Description}:
5288 Return the event count of the specified event variable.
5290 @item @emph{Syntax}:
5291 @code{void _gfortran_caf_event_query (caf_token_t token, size_t index,
5292 int image_index, int *count, int *stat)}
5294 @item @emph{Arguments}:
5295 @multitable @columnfractions .15 .70
5296 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5297 @item @var{index} @tab intent(in) Array index; first array index is 0. For
5298 scalars, it is always 0.
5299 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5300 positive number; zero indicates the current image when accessed noncoindexed.
5301 @item @var{count} @tab intent(out) The number of events currently posted to
5303 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
5307 The typical use is to check the local event variable to only call
5308 @code{event_wait} when the data is available. However, a coindexed variable
5309 is permitted; there is no ordering or synchronization implied. It acts like
5310 an atomic fetch of the value of the event variable.
5315 @node _gfortran_caf_sync_all
5316 @subsection @code{_gfortran_caf_sync_all} --- All-image barrier
5317 @cindex Coarray, _gfortran_caf_sync_all
5320 @item @emph{Description}:
5321 Synchronization of all images in the current team; the program only continues
5322 on a given image after this function has been called on all images of the
5323 current team. Additionally, it ensures that all pending data transfers of
5324 previous segment have completed.
5326 @item @emph{Syntax}:
5327 @code{void _gfortran_caf_sync_all (int *stat, char *errmsg, size_t errmsg_len)}
5329 @item @emph{Arguments}:
5330 @multitable @columnfractions .15 .70
5331 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5332 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5333 an error message; may be NULL.
5334 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5340 @node _gfortran_caf_sync_images
5341 @subsection @code{_gfortran_caf_sync_images} --- Barrier for selected images
5342 @cindex Coarray, _gfortran_caf_sync_images
5345 @item @emph{Description}:
5346 Synchronization between the specified images; the program only continues on a
5347 given image after this function has been called on all images specified for
5348 that image. Note that one image can wait for all other images in the current
5349 team (e.g. via @code{sync images(*)}) while those only wait for that specific
5350 image. Additionally, @code{sync images} ensures that all pending data
5351 transfers of previous segments have completed.
5353 @item @emph{Syntax}:
5354 @code{void _gfortran_caf_sync_images (int count, int images[], int *stat,
5355 char *errmsg, size_t errmsg_len)}
5357 @item @emph{Arguments}:
5358 @multitable @columnfractions .15 .70
5359 @item @var{count} @tab intent(in) The number of images which are provided in
5360 the next argument. For a zero-sized array, the value is zero. For
5361 @code{sync images (*)}, the value is @math{-1}.
5362 @item @var{images} @tab intent(in) An array with the images provided by the
5363 user. If @var{count} is zero, a NULL pointer is passed.
5364 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5365 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5366 an error message; may be NULL.
5367 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5373 @node _gfortran_caf_sync_memory
5374 @subsection @code{_gfortran_caf_sync_memory} --- Wait for completion of segment-memory operations
5375 @cindex Coarray, _gfortran_caf_sync_memory
5378 @item @emph{Description}:
5379 Acts as optimization barrier between different segments. It also ensures that
5380 all pending memory operations of this image have been completed.
5382 @item @emph{Syntax}:
5383 @code{void _gfortran_caf_sync_memory (int *stat, char *errmsg, size_t errmsg_len)}
5385 @item @emph{Arguments}:
5386 @multitable @columnfractions .15 .70
5387 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5388 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5389 an error message; may be NULL.
5390 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5393 @item @emph{NOTE} A simple implementation could be
5394 @code{__asm__ __volatile__ ("":::"memory")} to prevent code movements.
5399 @node _gfortran_caf_error_stop
5400 @subsection @code{_gfortran_caf_error_stop} --- Error termination with exit code
5401 @cindex Coarray, _gfortran_caf_error_stop
5404 @item @emph{Description}:
5405 Invoked for an @code{ERROR STOP} statement which has an integer argument. The
5406 function should terminate the program with the specified exit code.
5409 @item @emph{Syntax}:
5410 @code{void _gfortran_caf_error_stop (int error)}
5412 @item @emph{Arguments}:
5413 @multitable @columnfractions .15 .70
5414 @item @var{error} @tab intent(in) The exit status to be used.
5420 @node _gfortran_caf_error_stop_str
5421 @subsection @code{_gfortran_caf_error_stop_str} --- Error termination with string
5422 @cindex Coarray, _gfortran_caf_error_stop_str
5425 @item @emph{Description}:
5426 Invoked for an @code{ERROR STOP} statement which has a string as argument. The
5427 function should terminate the program with a nonzero-exit code.
5429 @item @emph{Syntax}:
5430 @code{void _gfortran_caf_error_stop (const char *string, size_t len)}
5432 @item @emph{Arguments}:
5433 @multitable @columnfractions .15 .70
5434 @item @var{string} @tab intent(in) the error message (not zero terminated)
5435 @item @var{len} @tab intent(in) the length of the string
5441 @node _gfortran_caf_fail_image
5442 @subsection @code{_gfortran_caf_fail_image} --- Mark the image failed and end its execution
5443 @cindex Coarray, _gfortran_caf_fail_image
5446 @item @emph{Description}:
5447 Invoked for an @code{FAIL IMAGE} statement. The function should terminate the
5450 @item @emph{Syntax}:
5451 @code{void _gfortran_caf_fail_image ()}
5454 This function follows TS18508.
5459 @node _gfortran_caf_atomic_define
5460 @subsection @code{_gfortran_caf_atomic_define} --- Atomic variable assignment
5461 @cindex Coarray, _gfortran_caf_atomic_define
5464 @item @emph{Description}:
5465 Assign atomically a value to an integer or logical variable.
5467 @item @emph{Syntax}:
5468 @code{void _gfortran_caf_atomic_define (caf_token_t token, size_t offset,
5469 int image_index, void *value, int *stat, int type, int kind)}
5471 @item @emph{Arguments}:
5472 @multitable @columnfractions .15 .70
5473 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5474 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5475 shifted compared to the base address of the coarray.
5476 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5477 positive number; zero indicates the current image when used noncoindexed.
5478 @item @var{value} @tab intent(in) the value to be assigned, passed by reference
5479 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5480 @item @var{type} @tab intent(in) The data type, i.e. @code{BT_INTEGER} (1) or
5481 @code{BT_LOGICAL} (2).
5482 @item @var{kind} @tab intent(in) The kind value (only 4; always @code{int})
5488 @node _gfortran_caf_atomic_ref
5489 @subsection @code{_gfortran_caf_atomic_ref} --- Atomic variable reference
5490 @cindex Coarray, _gfortran_caf_atomic_ref
5493 @item @emph{Description}:
5494 Reference atomically a value of a kind-4 integer or logical variable.
5496 @item @emph{Syntax}:
5497 @code{void _gfortran_caf_atomic_ref (caf_token_t token, size_t offset,
5498 int image_index, void *value, int *stat, int type, int kind)}
5500 @item @emph{Arguments}:
5501 @multitable @columnfractions .15 .70
5502 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5503 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5504 shifted compared to the base address of the coarray.
5505 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5506 positive number; zero indicates the current image when used noncoindexed.
5507 @item @var{value} @tab intent(out) The variable assigned the atomically
5508 referenced variable.
5509 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5510 @item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
5511 @code{BT_LOGICAL} (2).
5512 @item @var{kind} @tab The kind value (only 4; always @code{int})
5518 @node _gfortran_caf_atomic_cas
5519 @subsection @code{_gfortran_caf_atomic_cas} --- Atomic compare and swap
5520 @cindex Coarray, _gfortran_caf_atomic_cas
5523 @item @emph{Description}:
5524 Atomic compare and swap of a kind-4 integer or logical variable. Assigns
5525 atomically the specified value to the atomic variable, if the latter has
5526 the value specified by the passed condition value.
5528 @item @emph{Syntax}:
5529 @code{void _gfortran_caf_atomic_cas (caf_token_t token, size_t offset,
5530 int image_index, void *old, void *compare, void *new_val, int *stat,
5531 int type, int kind)}
5533 @item @emph{Arguments}:
5534 @multitable @columnfractions .15 .70
5535 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5536 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5537 shifted compared to the base address of the coarray.
5538 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5539 positive number; zero indicates the current image when used noncoindexed.
5540 @item @var{old} @tab intent(out) The value which the atomic variable had
5541 just before the cas operation.
5542 @item @var{compare} @tab intent(in) The value used for comparision.
5543 @item @var{new_val} @tab intent(in) The new value for the atomic variable,
5544 assigned to the atomic variable, if @code{compare} equals the value of the
5546 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5547 @item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or
5548 @code{BT_LOGICAL} (2).
5549 @item @var{kind} @tab intent(in) The kind value (only 4; always @code{int})
5555 @node _gfortran_caf_atomic_op
5556 @subsection @code{_gfortran_caf_atomic_op} --- Atomic operation
5557 @cindex Coarray, _gfortran_caf_atomic_op
5560 @item @emph{Description}:
5561 Apply an operation atomically to an atomic integer or logical variable.
5562 After the operation, @var{old} contains the value just before the operation,
5563 which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the @code{value} to
5564 the atomic integer variable or does a bitwise AND, OR or exclusive OR
5565 between the atomic variable and @var{value}; the result is then stored in the
5568 @item @emph{Syntax}:
5569 @code{void _gfortran_caf_atomic_op (int op, caf_token_t token, size_t offset,
5570 int image_index, void *value, void *old, int *stat, int type, int kind)}
5572 @item @emph{Arguments}:
5573 @multitable @columnfractions .15 .70
5574 @item @var{op} @tab intent(in) the operation to be performed; possible values
5575 @code{GFC_CAF_ATOMIC_ADD} (1), @code{GFC_CAF_ATOMIC_AND} (2),
5576 @code{GFC_CAF_ATOMIC_OR} (3), @code{GFC_CAF_ATOMIC_XOR} (4).
5577 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5578 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5579 shifted compared to the base address of the coarray.
5580 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5581 positive number; zero indicates the current image when used noncoindexed.
5582 @item @var{old} @tab intent(out) The value which the atomic variable had
5583 just before the atomic operation.
5584 @item @var{val} @tab intent(in) The new value for the atomic variable,
5585 assigned to the atomic variable, if @code{compare} equals the value of the
5587 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5588 @item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or
5589 @code{BT_LOGICAL} (2)
5590 @item @var{kind} @tab intent(in) the kind value (only 4; always @code{int})
5597 @node _gfortran_caf_co_broadcast
5598 @subsection @code{_gfortran_caf_co_broadcast} --- Sending data to all images
5599 @cindex Coarray, _gfortran_caf_co_broadcast
5602 @item @emph{Description}:
5603 Distribute a value from a given image to all other images in the team. Has to
5604 be called collectively.
5606 @item @emph{Syntax}:
5607 @code{void _gfortran_caf_co_broadcast (gfc_descriptor_t *a,
5608 int source_image, int *stat, char *errmsg, size_t errmsg_len)}
5610 @item @emph{Arguments}:
5611 @multitable @columnfractions .15 .70
5612 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5613 broadcasted (on @var{source_image}) or to be received (other images).
5614 @item @var{source_image} @tab intent(in) The ID of the image from which the
5615 data should be broadcasted.
5616 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5617 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5618 an error message; may be NULL.
5619 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg.
5625 @node _gfortran_caf_co_max
5626 @subsection @code{_gfortran_caf_co_max} --- Collective maximum reduction
5627 @cindex Coarray, _gfortran_caf_co_max
5630 @item @emph{Description}:
5631 Calculates for each array element of the variable @var{a} the maximum
5632 value for that element in the current team; if @var{result_image} has the
5633 value 0, the result shall be stored on all images, otherwise, only on the
5634 specified image. This function operates on numeric values and character
5637 @item @emph{Syntax}:
5638 @code{void _gfortran_caf_co_max (gfc_descriptor_t *a, int result_image,
5639 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5641 @item @emph{Arguments}:
5642 @multitable @columnfractions .15 .70
5643 @item @var{a} @tab intent(inout) An array descriptor for the data to be
5644 processed. On the destination image(s) the result overwrites the old content.
5645 @item @var{result_image} @tab intent(in) The ID of the image to which the
5646 reduced value should be copied to; if zero, it has to be copied to all images.
5647 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5648 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5649 an error message; may be NULL.
5650 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5651 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5655 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5656 all images except of the specified one become undefined; hence, the library may
5662 @node _gfortran_caf_co_min
5663 @subsection @code{_gfortran_caf_co_min} --- Collective minimum reduction
5664 @cindex Coarray, _gfortran_caf_co_min
5667 @item @emph{Description}:
5668 Calculates for each array element of the variable @var{a} the minimum
5669 value for that element in the current team; if @var{result_image} has the
5670 value 0, the result shall be stored on all images, otherwise, only on the
5671 specified image. This function operates on numeric values and character
5674 @item @emph{Syntax}:
5675 @code{void _gfortran_caf_co_min (gfc_descriptor_t *a, int result_image,
5676 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5678 @item @emph{Arguments}:
5679 @multitable @columnfractions .15 .70
5680 @item @var{a} @tab intent(inout) An array descriptor for the data to be
5681 processed. On the destination image(s) the result overwrites the old content.
5682 @item @var{result_image} @tab intent(in) The ID of the image to which the
5683 reduced value should be copied to; if zero, it has to be copied to all images.
5684 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5685 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5686 an error message; may be NULL.
5687 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5688 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5692 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5693 all images except of the specified one become undefined; hence, the library may
5699 @node _gfortran_caf_co_sum
5700 @subsection @code{_gfortran_caf_co_sum} --- Collective summing reduction
5701 @cindex Coarray, _gfortran_caf_co_sum
5704 @item @emph{Description}:
5705 Calculates for each array element of the variable @var{a} the sum of all
5706 values for that element in the current team; if @var{result_image} has the
5707 value 0, the result shall be stored on all images, otherwise, only on the
5708 specified image. This function operates on numeric values only.
5710 @item @emph{Syntax}:
5711 @code{void _gfortran_caf_co_sum (gfc_descriptor_t *a, int result_image,
5712 int *stat, char *errmsg, size_t errmsg_len)}
5714 @item @emph{Arguments}:
5715 @multitable @columnfractions .15 .70
5716 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5717 processed. On the destination image(s) the result overwrites the old content.
5718 @item @var{result_image} @tab intent(in) The ID of the image to which the
5719 reduced value should be copied to; if zero, it has to be copied to all images.
5720 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5721 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5722 an error message; may be NULL.
5723 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5727 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5728 all images except of the specified one become undefined; hence, the library may
5734 @node _gfortran_caf_co_reduce
5735 @subsection @code{_gfortran_caf_co_reduce} --- Generic collective reduction
5736 @cindex Coarray, _gfortran_caf_co_reduce
5739 @item @emph{Description}:
5740 Calculates for each array element of the variable @var{a} the reduction
5741 value for that element in the current team; if @var{result_image} has the
5742 value 0, the result shall be stored on all images, otherwise, only on the
5743 specified image. The @var{opr} is a pure function doing a mathematically
5744 commutative and associative operation.
5746 The @var{opr_flags} denote the following; the values are bitwise ored.
5747 @code{GFC_CAF_BYREF} (1) if the result should be returned
5748 by reference; @code{GFC_CAF_HIDDENLEN} (2) whether the result and argument
5749 string lengths shall be specified as hidden arguments;
5750 @code{GFC_CAF_ARG_VALUE} (4) whether the arguments shall be passed by value,
5751 @code{GFC_CAF_ARG_DESC} (8) whether the arguments shall be passed by descriptor.
5754 @item @emph{Syntax}:
5755 @code{void _gfortran_caf_co_reduce (gfc_descriptor_t *a,
5756 void * (*opr) (void *, void *), int opr_flags, int result_image,
5757 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5759 @item @emph{Arguments}:
5760 @multitable @columnfractions .15 .70
5761 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5762 processed. On the destination image(s) the result overwrites the old content.
5763 @item @var{opr} @tab intent(in) Function pointer to the reduction function
5764 @item @var{opr_flags} @tab intent(in) Flags regarding the reduction function
5765 @item @var{result_image} @tab intent(in) The ID of the image to which the
5766 reduced value should be copied to; if zero, it has to be copied to all images.
5767 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5768 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5769 an error message; may be NULL.
5770 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5771 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5775 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5776 all images except of the specified one become undefined; hence, the library may
5779 For character arguments, the result is passed as first argument, followed
5780 by the result string length, next come the two string arguments, followed
5781 by the two hidden string length arguments. With C binding, there are no hidden
5782 arguments and by-reference passing and either only a single character is passed
5783 or an array descriptor.
5787 @c Intrinsic Procedures
5788 @c ---------------------------------------------------------------------
5790 @include intrinsic.texi
5797 @c ---------------------------------------------------------------------
5799 @c ---------------------------------------------------------------------
5802 @unnumbered Contributing
5803 @cindex Contributing
5805 Free software is only possible if people contribute to efforts
5807 We're always in need of more people helping out with ideas
5808 and comments, writing documentation and contributing code.
5810 If you want to contribute to GNU Fortran,
5811 have a look at the long lists of projects you can take on.
5812 Some of these projects are small,
5813 some of them are large;
5814 some are completely orthogonal to the rest of what is
5815 happening on GNU Fortran,
5816 but others are ``mainstream'' projects in need of enthusiastic hackers.
5817 All of these projects are important!
5818 We will eventually get around to the things here,
5819 but they are also things doable by someone who is willing and able.
5824 * Proposed Extensions::
5829 @section Contributors to GNU Fortran
5830 @cindex Contributors
5834 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
5835 also the initiator of the whole project. Thanks Andy!
5836 Most of the interface with GCC was written by @emph{Paul Brook}.
5838 The following individuals have contributed code and/or
5839 ideas and significant help to the GNU Fortran project
5840 (in alphabetical order):
5843 @item Janne Blomqvist
5844 @item Steven Bosscher
5847 @item Fran@,{c}ois-Xavier Coudert
5851 @item Bernhard Fischer
5853 @item Richard Guenther
5854 @item Richard Henderson
5855 @item Katherine Holcomb
5857 @item Niels Kristian Bech Jensen
5858 @item Steven Johnson
5859 @item Steven G. Kargl
5867 @item Christopher D. Rickett
5868 @item Richard Sandiford
5869 @item Tobias Schl@"uter
5878 The following people have contributed bug reports,
5879 smaller or larger patches,
5880 and much needed feedback and encouragement for the
5881 GNU Fortran project:
5885 @item Dominique d'Humi@`eres
5887 @item Erik Schnetter
5888 @item Joost VandeVondele
5891 Many other individuals have helped debug,
5892 test and improve the GNU Fortran compiler over the past few years,
5893 and we welcome you to do the same!
5894 If you already have done so,
5895 and you would like to see your name listed in the
5896 list above, please contact us.
5904 @item Help build the test suite
5905 Solicit more code for donation to the test suite: the more extensive the
5906 testsuite, the smaller the risk of breaking things in the future! We can
5907 keep code private on request.
5909 @item Bug hunting/squishing
5910 Find bugs and write more test cases! Test cases are especially very
5911 welcome, because it allows us to concentrate on fixing bugs instead of
5912 isolating them. Going through the bugzilla database at
5913 @url{https://gcc.gnu.org/@/bugzilla/} to reduce testcases posted there and
5914 add more information (for example, for which version does the testcase
5915 work, for which versions does it fail?) is also very helpful.
5920 @node Proposed Extensions
5921 @section Proposed Extensions
5923 Here's a list of proposed extensions for the GNU Fortran compiler, in no particular
5924 order. Most of these are necessary to be fully compatible with
5925 existing Fortran compilers, but they are not part of the official
5926 J3 Fortran 95 standard.
5928 @subsection Compiler extensions:
5931 User-specified alignment rules for structures.
5934 Automatically extend single precision constants to double.
5937 Compile code that conserves memory by dynamically allocating common and
5938 module storage either on stack or heap.
5941 Compile flag to generate code for array conformance checking (suggest -CC).
5944 User control of symbol names (underscores, etc).
5947 Compile setting for maximum size of stack frame size before spilling
5948 parts to static or heap.
5951 Flag to force local variables into static space.
5954 Flag to force local variables onto stack.
5958 @subsection Environment Options
5961 Pluggable library modules for random numbers, linear algebra.
5962 LA should use BLAS calling conventions.
5965 Environment variables controlling actions on arithmetic exceptions like
5966 overflow, underflow, precision loss---Generate NaN, abort, default.
5970 Set precision for fp units that support it (i387).
5973 Variable for setting fp rounding mode.
5976 Variable to fill uninitialized variables with a user-defined bit
5980 Environment variable controlling filename that is opened for that unit
5984 Environment variable to clear/trash memory being freed.
5987 Environment variable to control tracing of allocations and frees.
5990 Environment variable to display allocated memory at normal program end.
5993 Environment variable for filename for * IO-unit.
5996 Environment variable for temporary file directory.
5999 Environment variable forcing standard output to be line buffered (Unix).
6004 @c ---------------------------------------------------------------------
6005 @c GNU General Public License
6006 @c ---------------------------------------------------------------------
6008 @include gpl_v3.texi
6012 @c ---------------------------------------------------------------------
6013 @c GNU Free Documentation License
6014 @c ---------------------------------------------------------------------
6020 @c ---------------------------------------------------------------------
6021 @c Funding Free Software
6022 @c ---------------------------------------------------------------------
6024 @include funding.texi
6026 @c ---------------------------------------------------------------------
6028 @c ---------------------------------------------------------------------
6031 @unnumbered Option Index
6032 @command{gfortran}'s command line options are indexed here without any
6033 initial @samp{-} or @samp{--}. Where an option has both positive and
6034 negative forms (such as -foption and -fno-option), relevant entries in
6035 the manual are indexed under the most appropriate form; it may sometimes
6036 be useful to look up both forms.
6040 @unnumbered Keyword Index