1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set copyrights-gfortran 1999-2018
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 and @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 While CPP is the de-facto standard for preprocessing Fortran code,
426 Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines
427 Conditional Compilation, which is not widely used and not directly
428 supported by the GNU Fortran compiler. You can use the program coco
429 to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}).
432 @c ---------------------------------------------------------------------
433 @c GNU Fortran and G77
434 @c ---------------------------------------------------------------------
436 @node GNU Fortran and G77
437 @section GNU Fortran and G77
439 @cindex @command{g77}
441 The GNU Fortran compiler is the successor to @command{g77}, the Fortran
442 77 front end included in GCC prior to version 4. It is an entirely new
443 program that has been designed to provide Fortran 95 support and
444 extensibility for future Fortran language standards, as well as providing
445 backwards compatibility for Fortran 77 and nearly all of the GNU language
446 extensions supported by @command{g77}.
449 @c ---------------------------------------------------------------------
451 @c ---------------------------------------------------------------------
454 @section Project Status
457 As soon as @command{gfortran} can parse all of the statements correctly,
458 it will be in the ``larva'' state.
459 When we generate code, the ``puppa'' state.
460 When @command{gfortran} is done,
461 we'll see if it will be a beautiful butterfly,
462 or just a big bug....
464 --Andy Vaught, April 2000
467 The start of the GNU Fortran 95 project was announced on
468 the GCC homepage in March 18, 2000
469 (even though Andy had already been working on it for a while,
472 The GNU Fortran compiler is able to compile nearly all
473 standard-compliant Fortran 95, Fortran 90, and Fortran 77 programs,
474 including a number of standard and non-standard extensions, and can be
475 used on real-world programs. In particular, the supported extensions
476 include OpenMP, Cray-style pointers, some old vendor extensions, and several
477 Fortran 2003 and Fortran 2008 features, including TR 15581. However, it is
478 still under development and has a few remaining rough edges.
479 There also is initial support for OpenACC.
480 Note that this is an experimental feature, incomplete, and subject to
481 change in future versions of GCC. See
482 @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
484 At present, the GNU Fortran compiler passes the
485 @uref{http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html,
486 NIST Fortran 77 Test Suite}, and produces acceptable results on the
487 @uref{http://www.netlib.org/lapack/faq.html#1.21, LAPACK Test Suite}.
488 It also provides respectable performance on
489 the @uref{http://www.polyhedron.com/fortran-compiler-comparisons/polyhedron-benchmark-suite,
491 compiler benchmarks} and the
492 @uref{http://www.netlib.org/benchmark/livermore,
493 Livermore Fortran Kernels test}. It has been used to compile a number of
494 large real-world programs, including
495 @uref{http://hirlam.org/, the HARMONIE and HIRLAM weather forecasting code} and
496 @uref{http://physical-chemistry.scb.uwa.edu.au/tonto/wiki/index.php/Main_Page,
497 the Tonto quantum chemistry package}; see
498 @url{https://gcc.gnu.org/@/wiki/@/GfortranApps} for an extended list.
500 Among other things, the GNU Fortran compiler is intended as a replacement
501 for G77. At this point, nearly all programs that could be compiled with
502 G77 can be compiled with GNU Fortran, although there are a few minor known
505 The primary work remaining to be done on GNU Fortran falls into three
506 categories: bug fixing (primarily regarding the treatment of invalid
507 code and providing useful error messages), improving the compiler
508 optimizations and the performance of compiled code, and extending the
509 compiler to support future standards---in particular, Fortran 2003,
510 Fortran 2008 and Fortran 2018.
513 @c ---------------------------------------------------------------------
515 @c ---------------------------------------------------------------------
522 * Varying Length Character Strings::
525 The GNU Fortran compiler implements
526 ISO/IEC 1539:1997 (Fortran 95). As such, it can also compile essentially all
527 standard-compliant Fortran 90 and Fortran 77 programs. It also supports
528 the ISO/IEC TR-15581 enhancements to allocatable arrays.
530 GNU Fortran also have a partial support for ISO/IEC 1539-1:2004
531 (Fortran 2003), ISO/IEC 1539-1:2010 (Fortran 2008), the Technical
532 Specification @code{Further Interoperability of Fortran with C}
533 (ISO/IEC TS 29113:2012). Full support of those standards and future
534 Fortran standards is planned. The current status of the support is
535 can be found in the @ref{Fortran 2003 status}, @ref{Fortran 2008
536 status}, @ref{TS 29113 status}, @ref{TS 18508 status} and @ref{Fortran
537 2018 status} sections of the documentation.
539 Additionally, the GNU Fortran compilers supports the OpenMP specification
540 (version 4.0 and most of the features of the 4.5 version,
541 @url{http://openmp.org/@/wp/@/openmp-specifications/}).
542 There also is initial support for the OpenACC specification (targeting
543 version 2.0, @uref{http://www.openacc.org/}).
544 Note that this is an experimental feature, incomplete, and subject to
545 change in future versions of GCC. See
546 @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
548 @node Varying Length Character Strings
549 @subsection Varying Length Character Strings
550 @cindex Varying length character strings
551 @cindex Varying length strings
552 @cindex strings, varying length
554 The Fortran 95 standard specifies in Part 2 (ISO/IEC 1539-2:2000)
555 varying length character strings. While GNU Fortran currently does not
556 support such strings directly, there exist two Fortran implementations
557 for them, which work with GNU Fortran. They can be found at
558 @uref{http://www.fortran.com/@/iso_varying_string.f95} and at
559 @uref{ftp://ftp.nag.co.uk/@/sc22wg5/@/ISO_VARYING_STRING/}.
561 Deferred-length character strings of Fortran 2003 supports part of
562 the features of @code{ISO_VARYING_STRING} and should be considered as
563 replacement. (Namely, allocatable or pointers of the type
564 @code{character(len=:)}.)
567 @c =====================================================================
568 @c PART I: INVOCATION REFERENCE
569 @c =====================================================================
572 \part{I}{Invoking GNU Fortran}
575 @c ---------------------------------------------------------------------
577 @c ---------------------------------------------------------------------
582 @c ---------------------------------------------------------------------
584 @c ---------------------------------------------------------------------
587 @chapter Runtime: Influencing runtime behavior with environment variables
588 @cindex environment variable
590 The behavior of the @command{gfortran} can be influenced by
591 environment variables.
593 Malformed environment variables are silently ignored.
596 * TMPDIR:: Directory for scratch files
597 * GFORTRAN_STDIN_UNIT:: Unit number for standard input
598 * GFORTRAN_STDOUT_UNIT:: Unit number for standard output
599 * GFORTRAN_STDERR_UNIT:: Unit number for standard error
600 * GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units.
601 * GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units.
602 * GFORTRAN_SHOW_LOCUS:: Show location for runtime errors
603 * GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted
604 * GFORTRAN_LIST_SEPARATOR:: Separator for list output
605 * GFORTRAN_CONVERT_UNIT:: Set endianness for unformatted I/O
606 * GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors
610 @section @env{TMPDIR}---Directory for scratch files
612 When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to
613 create the file in one of the potential directories by testing each
614 directory in the order below.
618 The environment variable @env{TMPDIR}, if it exists.
621 On the MinGW target, the directory returned by the @code{GetTempPath}
622 function. Alternatively, on the Cygwin target, the @env{TMP} and
623 @env{TEMP} environment variables, if they exist, in that order.
626 The @code{P_tmpdir} macro if it is defined, otherwise the directory
630 @node GFORTRAN_STDIN_UNIT
631 @section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input
633 This environment variable can be used to select the unit number
634 preconnected to standard input. This must be a positive integer.
635 The default value is 5.
637 @node GFORTRAN_STDOUT_UNIT
638 @section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output
640 This environment variable can be used to select the unit number
641 preconnected to standard output. This must be a positive integer.
642 The default value is 6.
644 @node GFORTRAN_STDERR_UNIT
645 @section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error
647 This environment variable can be used to select the unit number
648 preconnected to standard error. This must be a positive integer.
649 The default value is 0.
651 @node GFORTRAN_UNBUFFERED_ALL
652 @section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units
654 This environment variable controls whether all I/O is unbuffered. If
655 the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is
656 unbuffered. This will slow down small sequential reads and writes. If
657 the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered.
660 @node GFORTRAN_UNBUFFERED_PRECONNECTED
661 @section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units
663 The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls
664 whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) is unbuffered. If
665 the first letter is @samp{y}, @samp{Y} or @samp{1}, I/O is unbuffered. This
666 will slow down small sequential reads and writes. If the first letter
667 is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. This is the default.
669 @node GFORTRAN_SHOW_LOCUS
670 @section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors
672 If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and
673 line numbers for runtime errors are printed. If the first letter is
674 @samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers
675 for runtime errors. The default is to print the location.
677 @node GFORTRAN_OPTIONAL_PLUS
678 @section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted
680 If the first letter is @samp{y}, @samp{Y} or @samp{1},
681 a plus sign is printed
682 where permitted by the Fortran standard. If the first letter
683 is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed
684 in most cases. Default is not to print plus signs.
686 @node GFORTRAN_LIST_SEPARATOR
687 @section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output
689 This environment variable specifies the separator when writing
690 list-directed output. It may contain any number of spaces and
691 at most one comma. If you specify this on the command line,
692 be sure to quote spaces, as in
694 $ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out
696 when @command{a.out} is the compiled Fortran program that you want to run.
697 Default is a single space.
699 @node GFORTRAN_CONVERT_UNIT
700 @section @env{GFORTRAN_CONVERT_UNIT}---Set endianness for unformatted I/O
702 By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible
703 to change the representation of data for unformatted files.
704 The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable is:
706 GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ;
707 mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ;
708 exception: mode ':' unit_list | unit_list ;
709 unit_list: unit_spec | unit_list unit_spec ;
710 unit_spec: INTEGER | INTEGER '-' INTEGER ;
712 The variable consists of an optional default mode, followed by
713 a list of optional exceptions, which are separated by semicolons
714 from the preceding default and each other. Each exception consists
715 of a format and a comma-separated list of units. Valid values for
716 the modes are the same as for the @code{CONVERT} specifier:
719 @item @code{NATIVE} Use the native format. This is the default.
720 @item @code{SWAP} Swap between little- and big-endian.
721 @item @code{LITTLE_ENDIAN} Use the little-endian format
722 for unformatted files.
723 @item @code{BIG_ENDIAN} Use the big-endian format for unformatted files.
725 A missing mode for an exception is taken to mean @code{BIG_ENDIAN}.
726 Examples of values for @env{GFORTRAN_CONVERT_UNIT} are:
728 @item @code{'big_endian'} Do all unformatted I/O in big_endian mode.
729 @item @code{'little_endian;native:10-20,25'} Do all unformatted I/O
730 in little_endian mode, except for units 10 to 20 and 25, which are in
732 @item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native.
735 Setting the environment variables should be done on the command
736 line or via the @command{export}
737 command for @command{sh}-compatible shells and via @command{setenv}
738 for @command{csh}-compatible shells.
740 Example for @command{sh}:
743 $ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out
746 Example code for @command{csh}:
749 % setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20'
753 Using anything but the native representation for unformatted data
754 carries a significant speed overhead. If speed in this area matters
755 to you, it is best if you use this only for data that needs to be
758 @xref{CONVERT specifier}, for an alternative way to specify the
759 data representation for unformatted files. @xref{Runtime Options}, for
760 setting a default data representation for the whole program. The
761 @code{CONVERT} specifier overrides the @option{-fconvert} compile options.
763 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
764 environment variable will override the CONVERT specifier in the
765 open statement}. This is to give control over data formats to
766 users who do not have the source code of their program available.
768 @node GFORTRAN_ERROR_BACKTRACE
769 @section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors
771 If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to @samp{y},
772 @samp{Y} or @samp{1} (only the first letter is relevant) then a
773 backtrace is printed when a serious run-time error occurs. To disable
774 the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}.
775 Default is to print a backtrace unless the @option{-fno-backtrace}
776 compile option was used.
778 @c =====================================================================
779 @c PART II: LANGUAGE REFERENCE
780 @c =====================================================================
783 \part{II}{Language Reference}
786 @c ---------------------------------------------------------------------
787 @c Fortran standards status
788 @c ---------------------------------------------------------------------
790 @node Fortran standards status
791 @chapter Fortran standards status
794 * Fortran 2003 status::
795 * Fortran 2008 status::
798 * Fortran 2018 status::
801 @node Fortran 2003 status
802 @section Fortran 2003 status
804 GNU Fortran supports several Fortran 2003 features; an incomplete
805 list can be found below. See also the
806 @uref{https://gcc.gnu.org/wiki/Fortran2003, wiki page} about Fortran 2003.
809 @item Procedure pointers including procedure-pointer components with
810 @code{PASS} attribute.
812 @item Procedures which are bound to a derived type (type-bound procedures)
813 including @code{PASS}, @code{PROCEDURE} and @code{GENERIC}, and
814 operators bound to a type.
816 @item Abstract interfaces and type extension with the possibility to
817 override type-bound procedures or to have deferred binding.
819 @item Polymorphic entities (``@code{CLASS}'') for derived types and unlimited
820 polymorphism (``@code{CLASS(*)}'') -- including @code{SAME_TYPE_AS},
821 @code{EXTENDS_TYPE_OF} and @code{SELECT TYPE} for scalars and arrays and
824 @item Generic interface names, which have the same name as derived types,
825 are now supported. This allows one to write constructor functions. Note
826 that Fortran does not support static constructor functions. For static
827 variables, only default initialization or structure-constructor
828 initialization are available.
830 @item The @code{ASSOCIATE} construct.
832 @item Interoperability with C including enumerations,
834 @item In structure constructors the components with default values may be
837 @item Extensions to the @code{ALLOCATE} statement, allowing for a
838 type-specification with type parameter and for allocation and initialization
839 from a @code{SOURCE=} expression; @code{ALLOCATE} and @code{DEALLOCATE}
840 optionally return an error message string via @code{ERRMSG=}.
842 @item Reallocation on assignment: If an intrinsic assignment is
843 used, an allocatable variable on the left-hand side is automatically allocated
844 (if unallocated) or reallocated (if the shape is different). Currently, scalar
845 deferred character length left-hand sides are correctly handled but arrays
846 are not yet fully implemented.
848 @item Deferred-length character variables and scalar deferred-length character
849 components of derived types are supported. (Note that array-valued compoents
850 are not yet implemented.)
852 @item Transferring of allocations via @code{MOVE_ALLOC}.
854 @item The @code{PRIVATE} and @code{PUBLIC} attributes may be given individually
855 to derived-type components.
857 @item In pointer assignments, the lower bound may be specified and
858 the remapping of elements is supported.
860 @item For pointers an @code{INTENT} may be specified which affect the
861 association status not the value of the pointer target.
863 @item Intrinsics @code{command_argument_count}, @code{get_command},
864 @code{get_command_argument}, and @code{get_environment_variable}.
866 @item Support for Unicode characters (ISO 10646) and UTF-8, including
867 the @code{SELECTED_CHAR_KIND} and @code{NEW_LINE} intrinsic functions.
869 @item Support for binary, octal and hexadecimal (BOZ) constants in the
870 intrinsic functions @code{INT}, @code{REAL}, @code{CMPLX} and @code{DBLE}.
872 @item Support for namelist variables with allocatable and pointer
873 attribute and nonconstant length type parameter.
876 @cindex array, constructors
878 Array constructors using square brackets. That is, @code{[...]} rather
879 than @code{(/.../)}. Type-specification for array constructors like
880 @code{(/ some-type :: ... /)}.
882 @item Extensions to the specification and initialization expressions,
883 including the support for intrinsics with real and complex arguments.
885 @item Support for the asynchronous input/output syntax; however, the
886 data transfer is currently always synchronously performed.
889 @cindex @code{FLUSH} statement
890 @cindex statement, @code{FLUSH}
891 @code{FLUSH} statement.
894 @cindex @code{IOMSG=} specifier
895 @code{IOMSG=} specifier for I/O statements.
898 @cindex @code{ENUM} statement
899 @cindex @code{ENUMERATOR} statement
900 @cindex statement, @code{ENUM}
901 @cindex statement, @code{ENUMERATOR}
902 @opindex @code{fshort-enums}
903 Support for the declaration of enumeration constants via the
904 @code{ENUM} and @code{ENUMERATOR} statements. Interoperability with
905 @command{gcc} is guaranteed also for the case where the
906 @command{-fshort-enums} command line option is given.
913 @cindex @code{ALLOCATABLE} dummy arguments
914 @code{ALLOCATABLE} dummy arguments.
916 @cindex @code{ALLOCATABLE} function results
917 @code{ALLOCATABLE} function results
919 @cindex @code{ALLOCATABLE} components of derived types
920 @code{ALLOCATABLE} components of derived types
924 @cindex @code{STREAM} I/O
925 @cindex @code{ACCESS='STREAM'} I/O
926 The @code{OPEN} statement supports the @code{ACCESS='STREAM'} specifier,
927 allowing I/O without any record structure.
930 Namelist input/output for internal files.
932 @item Minor I/O features: Rounding during formatted output, using of
933 a decimal comma instead of a decimal point, setting whether a plus sign
934 should appear for positive numbers. On systems where @code{strtod} honours
935 the rounding mode, the rounding mode is also supported for input.
938 @cindex @code{PROTECTED} statement
939 @cindex statement, @code{PROTECTED}
940 The @code{PROTECTED} statement and attribute.
943 @cindex @code{VALUE} statement
944 @cindex statement, @code{VALUE}
945 The @code{VALUE} statement and attribute.
948 @cindex @code{VOLATILE} statement
949 @cindex statement, @code{VOLATILE}
950 The @code{VOLATILE} statement and attribute.
953 @cindex @code{IMPORT} statement
954 @cindex statement, @code{IMPORT}
955 The @code{IMPORT} statement, allowing to import
956 host-associated derived types.
958 @item The intrinsic modules @code{ISO_FORTRAN_ENVIRONMENT} is supported,
959 which contains parameters of the I/O units, storage sizes. Additionally,
960 procedures for C interoperability are available in the @code{ISO_C_BINDING}
964 @cindex @code{USE, INTRINSIC} statement
965 @cindex statement, @code{USE, INTRINSIC}
966 @cindex @code{ISO_FORTRAN_ENV} statement
967 @cindex statement, @code{ISO_FORTRAN_ENV}
968 @code{USE} statement with @code{INTRINSIC} and @code{NON_INTRINSIC}
969 attribute; supported intrinsic modules: @code{ISO_FORTRAN_ENV},
970 @code{ISO_C_BINDING}, @code{OMP_LIB} and @code{OMP_LIB_KINDS},
974 Renaming of operators in the @code{USE} statement.
979 @node Fortran 2008 status
980 @section Fortran 2008 status
982 The latest version of the Fortran standard is ISO/IEC 1539-1:2010, informally
983 known as Fortran 2008. The official version is available from International
984 Organization for Standardization (ISO) or its national member organizations.
985 The the final draft (FDIS) can be downloaded free of charge from
986 @url{http://www.nag.co.uk/@/sc22wg5/@/links.html}. Fortran is developed by the
987 Working Group 5 of Sub-Committee 22 of the Joint Technical Committee 1 of the
988 International Organization for Standardization and the International
989 Electrotechnical Commission (IEC). This group is known as
990 @uref{http://www.nag.co.uk/sc22wg5/, WG5}.
992 The GNU Fortran compiler supports several of the new features of Fortran 2008;
993 the @uref{https://gcc.gnu.org/wiki/Fortran2008Status, wiki} has some information
994 about the current Fortran 2008 implementation status. In particular, the
995 following is implemented.
998 @item The @option{-std=f2008} option and support for the file extensions
999 @file{.f08} and @file{.F08}.
1001 @item The @code{OPEN} statement now supports the @code{NEWUNIT=} option,
1002 which returns a unique file unit, thus preventing inadvertent use of the
1003 same unit in different parts of the program.
1005 @item The @code{g0} format descriptor and unlimited format items.
1007 @item The mathematical intrinsics @code{ASINH}, @code{ACOSH}, @code{ATANH},
1008 @code{ERF}, @code{ERFC}, @code{GAMMA}, @code{LOG_GAMMA}, @code{BESSEL_J0},
1009 @code{BESSEL_J1}, @code{BESSEL_JN}, @code{BESSEL_Y0}, @code{BESSEL_Y1},
1010 @code{BESSEL_YN}, @code{HYPOT}, @code{NORM2}, and @code{ERFC_SCALED}.
1012 @item Using complex arguments with @code{TAN}, @code{SINH}, @code{COSH},
1013 @code{TANH}, @code{ASIN}, @code{ACOS}, and @code{ATAN} is now possible;
1014 @code{ATAN}(@var{Y},@var{X}) is now an alias for @code{ATAN2}(@var{Y},@var{X}).
1016 @item Support of the @code{PARITY} intrinsic functions.
1018 @item The following bit intrinsics: @code{LEADZ} and @code{TRAILZ} for
1019 counting the number of leading and trailing zero bits, @code{POPCNT} and
1020 @code{POPPAR} for counting the number of one bits and returning the parity;
1021 @code{BGE}, @code{BGT}, @code{BLE}, and @code{BLT} for bitwise comparisons;
1022 @code{DSHIFTL} and @code{DSHIFTR} for combined left and right shifts,
1023 @code{MASKL} and @code{MASKR} for simple left and right justified masks,
1024 @code{MERGE_BITS} for a bitwise merge using a mask, @code{SHIFTA},
1025 @code{SHIFTL} and @code{SHIFTR} for shift operations, and the
1026 transformational bit intrinsics @code{IALL}, @code{IANY} and @code{IPARITY}.
1028 @item Support of the @code{EXECUTE_COMMAND_LINE} intrinsic subroutine.
1030 @item Support for the @code{STORAGE_SIZE} intrinsic inquiry function.
1032 @item The @code{INT@{8,16,32@}} and @code{REAL@{32,64,128@}} kind type
1033 parameters and the array-valued named constants @code{INTEGER_KINDS},
1034 @code{LOGICAL_KINDS}, @code{REAL_KINDS} and @code{CHARACTER_KINDS} of
1035 the intrinsic module @code{ISO_FORTRAN_ENV}.
1037 @item The module procedures @code{C_SIZEOF} of the intrinsic module
1038 @code{ISO_C_BINDINGS} and @code{COMPILER_VERSION} and @code{COMPILER_OPTIONS}
1039 of @code{ISO_FORTRAN_ENV}.
1041 @item Coarray support for serial programs with @option{-fcoarray=single} flag
1042 and experimental support for multiple images with the @option{-fcoarray=lib}
1045 @item Submodules are supported. It should noted that @code{MODULEs} do not
1046 produce the smod file needed by the descendent @code{SUBMODULEs} unless they
1047 contain at least one @code{MODULE PROCEDURE} interface. The reason for this is
1048 that @code{SUBMODULEs} are useless without @code{MODULE PROCEDUREs}. See
1049 http://j3-fortran.org/doc/meeting/207/15-209.txt for a discussion and a draft
1050 interpretation. Adopting this interpretation has the advantage that code that
1051 does not use submodules does not generate smod files.
1053 @item The @code{DO CONCURRENT} construct is supported.
1055 @item The @code{BLOCK} construct is supported.
1057 @item The @code{STOP} and the new @code{ERROR STOP} statements now
1058 support all constant expressions. Both show the signals which were signaling
1061 @item Support for the @code{CONTIGUOUS} attribute.
1063 @item Support for @code{ALLOCATE} with @code{MOLD}.
1065 @item Support for the @code{IMPURE} attribute for procedures, which
1066 allows for @code{ELEMENTAL} procedures without the restrictions of
1069 @item Null pointers (including @code{NULL()}) and not-allocated variables
1070 can be used as actual argument to optional non-pointer, non-allocatable
1071 dummy arguments, denoting an absent argument.
1073 @item Non-pointer variables with @code{TARGET} attribute can be used as
1074 actual argument to @code{POINTER} dummies with @code{INTENT(IN)}.
1076 @item Pointers including procedure pointers and those in a derived
1077 type (pointer components) can now be initialized by a target instead
1078 of only by @code{NULL}.
1080 @item The @code{EXIT} statement (with construct-name) can be now be
1081 used to leave not only the @code{DO} but also the @code{ASSOCIATE},
1082 @code{BLOCK}, @code{IF}, @code{SELECT CASE} and @code{SELECT TYPE}
1085 @item Internal procedures can now be used as actual argument.
1087 @item Minor features: obsolesce diagnostics for @code{ENTRY} with
1088 @option{-std=f2008}; a line may start with a semicolon; for internal
1089 and module procedures @code{END} can be used instead of
1090 @code{END SUBROUTINE} and @code{END FUNCTION}; @code{SELECTED_REAL_KIND}
1091 now also takes a @code{RADIX} argument; intrinsic types are supported
1092 for @code{TYPE}(@var{intrinsic-type-spec}); multiple type-bound procedures
1093 can be declared in a single @code{PROCEDURE} statement; implied-shape
1094 arrays are supported for named constants (@code{PARAMETER}).
1099 @node TS 29113 status
1100 @section Technical Specification 29113 Status
1102 GNU Fortran supports some of the new features of the Technical
1103 Specification (TS) 29113 on Further Interoperability of Fortran with C.
1104 The @uref{https://gcc.gnu.org/wiki/TS29113Status, wiki} has some information
1105 about the current TS 29113 implementation status. In particular, the
1106 following is implemented.
1108 See also @ref{Further Interoperability of Fortran with C}.
1111 @item The @option{-std=f2008ts} option.
1113 @item The @code{OPTIONAL} attribute is allowed for dummy arguments
1114 of @code{BIND(C) procedures.}
1116 @item The @code{RANK} intrinsic is supported.
1118 @item GNU Fortran's implementation for variables with @code{ASYNCHRONOUS}
1119 attribute is compatible with TS 29113.
1121 @item Assumed types (@code{TYPE(*)}).
1123 @item Assumed-rank (@code{DIMENSION(..)}). However, the array descriptor
1124 of the TS is not yet supported.
1128 @node TS 18508 status
1129 @section Technical Specification 18508 Status
1131 GNU Fortran supports the following new features of the Technical
1132 Specification 18508 on Additional Parallel Features in Fortran:
1135 @item The new atomic ADD, CAS, FETCH and ADD/OR/XOR, OR and XOR intrinsics.
1137 @item The @code{CO_MIN} and @code{CO_MAX} and @code{SUM} reduction intrinsics.
1138 And the @code{CO_BROADCAST} and @code{CO_REDUCE} intrinsic, except that those
1139 do not support polymorphic types or types with allocatable, pointer or
1140 polymorphic components.
1142 @item Events (@code{EVENT POST}, @code{EVENT WAIT}, @code{EVENT_QUERY})
1144 @item Failed images (@code{FAIL IMAGE}, @code{IMAGE_STATUS},
1145 @code{FAILED_IMAGES}, @code{STOPPED_IMAGES})
1150 @node Fortran 2018 status
1151 @section Status of Fortran 2018 support
1153 So far very little work has been done to support Fortran 2018.
1156 @item ERROR STOP in a PURE procedure
1157 An @code{ERROR STOP} statement is permitted in a @code{PURE}
1160 @item IMPLICIT NONE with a spec-list
1161 Support the @code{IMPLICIT NONE} statement with an
1162 @code{implicit-none-spec-list}.
1164 @item Behavior of INQUIRE with the RECL= specifier
1166 The behavior of the @code{INQUIRE} statement with the @code{RECL=}
1167 specifier now conforms to Fortran 2018.
1171 @c ---------------------------------------------------------------------
1172 @c Compiler Characteristics
1173 @c ---------------------------------------------------------------------
1175 @node Compiler Characteristics
1176 @chapter Compiler Characteristics
1178 This chapter describes certain characteristics of the GNU Fortran
1179 compiler, that are not specified by the Fortran standard, but which
1180 might in some way or another become visible to the programmer.
1183 * KIND Type Parameters::
1184 * Internal representation of LOGICAL variables::
1185 * Thread-safety of the runtime library::
1186 * Data consistency and durability::
1187 * Files opened without an explicit ACTION= specifier::
1188 * File operations on symbolic links::
1189 * File format of unformatted sequential files::
1193 @node KIND Type Parameters
1194 @section KIND Type Parameters
1197 The @code{KIND} type parameters supported by GNU Fortran for the primitive
1203 1, 2, 4, 8*, 16*, default: 4**
1206 1, 2, 4, 8*, 16*, default: 4**
1209 4, 8, 10*, 16*, default: 4***
1212 4, 8, 10*, 16*, default: 4***
1214 @item DOUBLE PRECISION
1215 4, 8, 10*, 16*, default: 8***
1223 * not available on all systems @*
1224 ** unless @option{-fdefault-integer-8} is used @*
1225 *** unless @option{-fdefault-real-8} is used (see @ref{Fortran Dialect Options})
1228 The @code{KIND} value matches the storage size in bytes, except for
1229 @code{COMPLEX} where the storage size is twice as much (or both real and
1230 imaginary part are a real value of the given size). It is recommended to use
1231 the @ref{SELECTED_CHAR_KIND}, @ref{SELECTED_INT_KIND} and
1232 @ref{SELECTED_REAL_KIND} intrinsics or the @code{INT8}, @code{INT16},
1233 @code{INT32}, @code{INT64}, @code{REAL32}, @code{REAL64}, and @code{REAL128}
1234 parameters of the @code{ISO_FORTRAN_ENV} module instead of the concrete values.
1235 The available kind parameters can be found in the constant arrays
1236 @code{CHARACTER_KINDS}, @code{INTEGER_KINDS}, @code{LOGICAL_KINDS} and
1237 @code{REAL_KINDS} in the @ref{ISO_FORTRAN_ENV} module. For C interoperability,
1238 the kind parameters of the @ref{ISO_C_BINDING} module should be used.
1241 @node Internal representation of LOGICAL variables
1242 @section Internal representation of LOGICAL variables
1243 @cindex logical, variable representation
1245 The Fortran standard does not specify how variables of @code{LOGICAL}
1246 type are represented, beyond requiring that @code{LOGICAL} variables
1247 of default kind have the same storage size as default @code{INTEGER}
1248 and @code{REAL} variables. The GNU Fortran internal representation is
1251 A @code{LOGICAL(KIND=N)} variable is represented as an
1252 @code{INTEGER(KIND=N)} variable, however, with only two permissible
1253 values: @code{1} for @code{.TRUE.} and @code{0} for
1254 @code{.FALSE.}. Any other integer value results in undefined behavior.
1256 See also @ref{Argument passing conventions} and @ref{Interoperability with C}.
1259 @node Thread-safety of the runtime library
1260 @section Thread-safety of the runtime library
1261 @cindex thread-safety, threads
1263 GNU Fortran can be used in programs with multiple threads, e.g.@: by
1264 using OpenMP, by calling OS thread handling functions via the
1265 @code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code
1266 being called from a multi-threaded program.
1268 The GNU Fortran runtime library, (@code{libgfortran}), supports being
1269 called concurrently from multiple threads with the following
1272 During library initialization, the C @code{getenv} function is used,
1273 which need not be thread-safe. Similarly, the @code{getenv}
1274 function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and
1275 @code{GETENV} intrinsics. It is the responsibility of the user to
1276 ensure that the environment is not being updated concurrently when any
1277 of these actions are taking place.
1279 The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are
1280 implemented with the @code{system} function, which need not be
1281 thread-safe. It is the responsibility of the user to ensure that
1282 @code{system} is not called concurrently.
1284 For platforms not supporting thread-safe POSIX functions, further
1285 functionality might not be thread-safe. For details, please consult
1286 the documentation for your operating system.
1288 The GNU Fortran runtime library uses various C library functions that
1289 depend on the locale, such as @code{strtod} and @code{snprintf}. In
1290 order to work correctly in locale-aware programs that set the locale
1291 using @code{setlocale}, the locale is reset to the default ``C''
1292 locale while executing a formatted @code{READ} or @code{WRITE}
1293 statement. On targets supporting the POSIX 2008 per-thread locale
1294 functions (e.g. @code{newlocale}, @code{uselocale},
1295 @code{freelocale}), these are used and thus the global locale set
1296 using @code{setlocale} or the per-thread locales in other threads are
1297 not affected. However, on targets lacking this functionality, the
1298 global LC_NUMERIC locale is set to ``C'' during the formatted I/O.
1299 Thus, on such targets it's not safe to call @code{setlocale}
1300 concurrently from another thread while a Fortran formatted I/O
1301 operation is in progress. Also, other threads doing something
1302 dependent on the LC_NUMERIC locale might not work correctly if a
1303 formatted I/O operation is in progress in another thread.
1305 @node Data consistency and durability
1306 @section Data consistency and durability
1307 @cindex consistency, durability
1309 This section contains a brief overview of data and metadata
1310 consistency and durability issues when doing I/O.
1312 With respect to durability, GNU Fortran makes no effort to ensure that
1313 data is committed to stable storage. If this is required, the GNU
1314 Fortran programmer can use the intrinsic @code{FNUM} to retrieve the
1315 low level file descriptor corresponding to an open Fortran unit. Then,
1316 using e.g. the @code{ISO_C_BINDING} feature, one can call the
1317 underlying system call to flush dirty data to stable storage, such as
1318 @code{fsync} on POSIX, @code{_commit} on MingW, or @code{fcntl(fd,
1319 F_FULLSYNC, 0)} on Mac OS X. The following example shows how to call
1323 ! Declare the interface for POSIX fsync function
1325 function fsync (fd) bind(c,name="fsync")
1326 use iso_c_binding, only: c_int
1327 integer(c_int), value :: fd
1328 integer(c_int) :: fsync
1332 ! Variable declaration
1336 open (10,file="foo")
1339 ! Perform I/O on unit 10
1344 ret = fsync(fnum(10))
1346 ! Handle possible error
1347 if (ret /= 0) stop "Error calling FSYNC"
1350 With respect to consistency, for regular files GNU Fortran uses
1351 buffered I/O in order to improve performance. This buffer is flushed
1352 automatically when full and in some other situations, e.g. when
1353 closing a unit. It can also be explicitly flushed with the
1354 @code{FLUSH} statement. Also, the buffering can be turned off with the
1355 @code{GFORTRAN_UNBUFFERED_ALL} and
1356 @code{GFORTRAN_UNBUFFERED_PRECONNECTED} environment variables. Special
1357 files, such as terminals and pipes, are always unbuffered. Sometimes,
1358 however, further things may need to be done in order to allow other
1359 processes to see data that GNU Fortran has written, as follows.
1361 The Windows platform supports a relaxed metadata consistency model,
1362 where file metadata is written to the directory lazily. This means
1363 that, for instance, the @code{dir} command can show a stale size for a
1364 file. One can force a directory metadata update by closing the unit,
1365 or by calling @code{_commit} on the file descriptor. Note, though,
1366 that @code{_commit} will force all dirty data to stable storage, which
1367 is often a very slow operation.
1369 The Network File System (NFS) implements a relaxed consistency model
1370 called open-to-close consistency. Closing a file forces dirty data and
1371 metadata to be flushed to the server, and opening a file forces the
1372 client to contact the server in order to revalidate cached
1373 data. @code{fsync} will also force a flush of dirty data and metadata
1374 to the server. Similar to @code{open} and @code{close}, acquiring and
1375 releasing @code{fcntl} file locks, if the server supports them, will
1376 also force cache validation and flushing dirty data and metadata.
1379 @node Files opened without an explicit ACTION= specifier
1380 @section Files opened without an explicit ACTION= specifier
1381 @cindex open, action
1383 The Fortran standard says that if an @code{OPEN} statement is executed
1384 without an explicit @code{ACTION=} specifier, the default value is
1385 processor dependent. GNU Fortran behaves as follows:
1388 @item Attempt to open the file with @code{ACTION='READWRITE'}
1389 @item If that fails, try to open with @code{ACTION='READ'}
1390 @item If that fails, try to open with @code{ACTION='WRITE'}
1391 @item If that fails, generate an error
1395 @node File operations on symbolic links
1396 @section File operations on symbolic links
1397 @cindex file, symbolic link
1399 This section documents the behavior of GNU Fortran for file operations on
1400 symbolic links, on systems that support them.
1404 @item Results of INQUIRE statements of the ``inquire by file'' form will
1405 relate to the target of the symbolic link. For example,
1406 @code{INQUIRE(FILE="foo",EXIST=ex)} will set @var{ex} to @var{.true.} if
1407 @var{foo} is a symbolic link pointing to an existing file, and @var{.false.}
1408 if @var{foo} points to an non-existing file (``dangling'' symbolic link).
1410 @item Using the @code{OPEN} statement with a @code{STATUS="NEW"} specifier
1411 on a symbolic link will result in an error condition, whether the symbolic
1412 link points to an existing target or is dangling.
1414 @item If a symbolic link was connected, using the @code{CLOSE} statement
1415 with a @code{STATUS="DELETE"} specifier will cause the symbolic link itself
1416 to be deleted, not its target.
1420 @node File format of unformatted sequential files
1421 @section File format of unformatted sequential files
1422 @cindex file, unformatted sequential
1423 @cindex unformatted sequential
1424 @cindex sequential, unformatted
1425 @cindex record marker
1428 Unformatted sequential files are stored as logical records using
1429 record markers. Each logical record consists of one of more
1432 Each subrecord consists of a leading record marker, the data written
1433 by the user program, and a trailing record marker. The record markers
1434 are four-byte integers by default, and eight-byte integers if the
1435 @option{-fmax-subrecord-length=8} option (which exists for backwards
1436 compability only) is in effect.
1438 The representation of the record markers is that of unformatted files
1439 given with the @option{-fconvert} option, the @xref{CONVERT specifier}
1440 on the open statement or the @xref{GFORTRAN_CONVERT_UNIT} environment
1443 The maximum number of bytes of user data in a subrecord is 2147483639
1444 (2 GiB - 9) for a four-byte record marker. This limit can be lowered
1445 with the @option{-fmax-subrecord-length} option, altough this is
1446 rarely useful. If the length of a logical record exceeds this limit,
1447 the data is distributed among several subrecords.
1449 The absolute of the number stored in the record markers is the number
1450 of bytes of user data in the corresponding subrecord. If the leading
1451 record marker of a subrecord contains a negative number, another
1452 subrecord follows the current one. If the trailing record marker
1453 contains a negative number, then there is a preceding subrecord.
1455 In the most simple case, with only one subrecord per logical record,
1456 both record markers contain the number of bytes of user data in the
1459 The format for unformatted sequential data can be duplicated using
1460 unformatted stream, as shown in the example program for an unformatted
1461 record containing a single subrecord:
1465 use iso_fortran_env, only: int32
1468 real, dimension(10) :: a, b
1469 call random_number(a)
1470 open (10,file='test.dat',form='unformatted',access='stream')
1471 inquire (iolength=i) a
1474 open (10,file='test.dat',form='unformatted')
1476 if (all (a == b)) print *,'success!'
1480 @c ---------------------------------------------------------------------
1482 @c ---------------------------------------------------------------------
1484 @c Maybe this chapter should be merged with the 'Standards' section,
1485 @c whenever that is written :-)
1491 The two sections below detail the extensions to standard Fortran that are
1492 implemented in GNU Fortran, as well as some of the popular or
1493 historically important extensions that are not (or not yet) implemented.
1494 For the latter case, we explain the alternatives available to GNU Fortran
1495 users, including replacement by standard-conforming code or GNU
1499 * Extensions implemented in GNU Fortran::
1500 * Extensions not implemented in GNU Fortran::
1504 @node Extensions implemented in GNU Fortran
1505 @section Extensions implemented in GNU Fortran
1506 @cindex extensions, implemented
1508 GNU Fortran implements a number of extensions over standard Fortran.
1509 This chapter contains information on their syntax and meaning. There
1510 are currently two categories of GNU Fortran extensions, those that
1511 provide functionality beyond that provided by any standard, and those
1512 that are supported by GNU Fortran purely for backward compatibility
1513 with legacy compilers. By default, @option{-std=gnu} allows the
1514 compiler to accept both types of extensions, but to warn about the use
1515 of the latter. Specifying either @option{-std=f95},
1516 @option{-std=f2003}, @option{-std=f2008}, or @option{-std=f2018}
1517 disables both types of extensions, and @option{-std=legacy} allows
1518 both without warning. The special compile flag @option{-fdec} enables
1519 additional compatibility extensions along with those enabled by
1520 @option{-std=legacy}.
1523 * Old-style kind specifications::
1524 * Old-style variable initialization::
1525 * Extensions to namelist::
1526 * X format descriptor without count field::
1527 * Commas in FORMAT specifications::
1528 * Missing period in FORMAT specifications::
1530 * @code{Q} exponent-letter::
1531 * BOZ literal constants::
1532 * Real array indices::
1534 * Implicitly convert LOGICAL and INTEGER values::
1535 * Hollerith constants support::
1537 * CONVERT specifier::
1540 * Argument list functions::
1541 * Read/Write after EOF marker::
1542 * STRUCTURE and RECORD::
1544 * Type variants for integer intrinsics::
1545 * AUTOMATIC and STATIC attributes::
1546 * Extended math intrinsics::
1547 * Form feed as whitespace::
1548 * TYPE as an alias for PRINT::
1549 * %LOC as an rvalue::
1551 * Bitwise logical operators::
1552 * Extended I/O specifiers::
1553 * Legacy PARAMETER statements::
1554 * Default exponents::
1557 @node Old-style kind specifications
1558 @subsection Old-style kind specifications
1559 @cindex kind, old-style
1561 GNU Fortran allows old-style kind specifications in declarations. These
1567 where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
1568 etc.), and where @code{size} is a byte count corresponding to the
1569 storage size of a valid kind for that type. (For @code{COMPLEX}
1570 variables, @code{size} is the total size of the real and imaginary
1571 parts.) The statement then declares @code{x}, @code{y} and @code{z} to
1572 be of type @code{TYPESPEC} with the appropriate kind. This is
1573 equivalent to the standard-conforming declaration
1578 where @code{k} is the kind parameter suitable for the intended precision. As
1579 kind parameters are implementation-dependent, use the @code{KIND},
1580 @code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve
1581 the correct value, for instance @code{REAL*8 x} can be replaced by:
1583 INTEGER, PARAMETER :: dbl = KIND(1.0d0)
1587 @node Old-style variable initialization
1588 @subsection Old-style variable initialization
1590 GNU Fortran allows old-style initialization of variables of the
1594 REAL x(2,2) /3*0.,1./
1596 The syntax for the initializers is as for the @code{DATA} statement, but
1597 unlike in a @code{DATA} statement, an initializer only applies to the
1598 variable immediately preceding the initialization. In other words,
1599 something like @code{INTEGER I,J/2,3/} is not valid. This style of
1600 initialization is only allowed in declarations without double colons
1601 (@code{::}); the double colons were introduced in Fortran 90, which also
1602 introduced a standard syntax for initializing variables in type
1605 Examples of standard-conforming code equivalent to the above example
1609 INTEGER :: i = 1, j = 2
1610 REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
1614 DATA i/1/, j/2/, x/3*0.,1./
1617 Note that variables which are explicitly initialized in declarations
1618 or in @code{DATA} statements automatically acquire the @code{SAVE}
1621 @node Extensions to namelist
1622 @subsection Extensions to namelist
1625 GNU Fortran fully supports the Fortran 95 standard for namelist I/O
1626 including array qualifiers, substrings and fully qualified derived types.
1627 The output from a namelist write is compatible with namelist read. The
1628 output has all names in upper case and indentation to column 1 after the
1629 namelist name. Two extensions are permitted:
1631 Old-style use of @samp{$} instead of @samp{&}
1634 X(:)%Y(2) = 1.0 2.0 3.0
1639 It should be noted that the default terminator is @samp{/} rather than
1642 Querying of the namelist when inputting from stdin. After at least
1643 one space, entering @samp{?} sends to stdout the namelist name and the names of
1644 the variables in the namelist:
1655 Entering @samp{=?} outputs the namelist to stdout, as if
1656 @code{WRITE(*,NML = mynml)} had been called:
1661 X(1)%Y= 0.000000 , 1.000000 , 0.000000 ,
1662 X(2)%Y= 0.000000 , 2.000000 , 0.000000 ,
1663 X(3)%Y= 0.000000 , 3.000000 , 0.000000 ,
1667 To aid this dialog, when input is from stdin, errors send their
1668 messages to stderr and execution continues, even if @code{IOSTAT} is set.
1670 @code{PRINT} namelist is permitted. This causes an error if
1671 @option{-std=f95} is used.
1674 REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/)
1677 END PROGRAM test_print
1680 Expanded namelist reads are permitted. This causes an error if
1681 @option{-std=f95} is used. In the following example, the first element
1682 of the array will be given the value 0.00 and the two succeeding
1683 elements will be given the values 1.00 and 2.00.
1686 X(1,1) = 0.00 , 1.00 , 2.00
1690 When writing a namelist, if no @code{DELIM=} is specified, by default a
1691 double quote is used to delimit character strings. If -std=F95, F2003,
1692 or F2008, etc, the delim status is set to 'none'. Defaulting to
1693 quotes ensures that namelists with character strings can be subsequently
1694 read back in accurately.
1696 @node X format descriptor without count field
1697 @subsection @code{X} format descriptor without count field
1699 To support legacy codes, GNU Fortran permits the count field of the
1700 @code{X} edit descriptor in @code{FORMAT} statements to be omitted.
1701 When omitted, the count is implicitly assumed to be one.
1705 10 FORMAT (I1, X, I1)
1708 @node Commas in FORMAT specifications
1709 @subsection Commas in @code{FORMAT} specifications
1711 To support legacy codes, GNU Fortran allows the comma separator
1712 to be omitted immediately before and after character string edit
1713 descriptors in @code{FORMAT} statements.
1717 10 FORMAT ('FOO='I1' BAR='I2)
1721 @node Missing period in FORMAT specifications
1722 @subsection Missing period in @code{FORMAT} specifications
1724 To support legacy codes, GNU Fortran allows missing periods in format
1725 specifications if and only if @option{-std=legacy} is given on the
1726 command line. This is considered non-conforming code and is
1735 @node I/O item lists
1736 @subsection I/O item lists
1737 @cindex I/O item lists
1739 To support legacy codes, GNU Fortran allows the input item list
1740 of the @code{READ} statement, and the output item lists of the
1741 @code{WRITE} and @code{PRINT} statements, to start with a comma.
1743 @node @code{Q} exponent-letter
1744 @subsection @code{Q} exponent-letter
1745 @cindex @code{Q} exponent-letter
1747 GNU Fortran accepts real literal constants with an exponent-letter
1748 of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted
1749 as a @code{REAL(16)} entity on targets that support this type. If
1750 the target does not support @code{REAL(16)} but has a @code{REAL(10)}
1751 type, then the real-literal-constant will be interpreted as a
1752 @code{REAL(10)} entity. In the absence of @code{REAL(16)} and
1753 @code{REAL(10)}, an error will occur.
1755 @node BOZ literal constants
1756 @subsection BOZ literal constants
1757 @cindex BOZ literal constants
1759 Besides decimal constants, Fortran also supports binary (@code{b}),
1760 octal (@code{o}) and hexadecimal (@code{z}) integer constants. The
1761 syntax is: @samp{prefix quote digits quote}, were the prefix is
1762 either @code{b}, @code{o} or @code{z}, quote is either @code{'} or
1763 @code{"} and the digits are for binary @code{0} or @code{1}, for
1764 octal between @code{0} and @code{7}, and for hexadecimal between
1765 @code{0} and @code{F}. (Example: @code{b'01011101'}.)
1767 Up to Fortran 95, BOZ literals were only allowed to initialize
1768 integer variables in DATA statements. Since Fortran 2003 BOZ literals
1769 are also allowed as argument of @code{REAL}, @code{DBLE}, @code{INT}
1770 and @code{CMPLX}; the result is the same as if the integer BOZ
1771 literal had been converted by @code{TRANSFER} to, respectively,
1772 @code{real}, @code{double precision}, @code{integer} or @code{complex}.
1773 As GNU Fortran extension the intrinsic procedures @code{FLOAT},
1774 @code{DFLOAT}, @code{COMPLEX} and @code{DCMPLX} are treated alike.
1776 As an extension, GNU Fortran allows hexadecimal BOZ literal constants to
1777 be specified using the @code{X} prefix, in addition to the standard
1778 @code{Z} prefix. The BOZ literal can also be specified by adding a
1779 suffix to the string, for example, @code{Z'ABC'} and @code{'ABC'Z} are
1782 Furthermore, GNU Fortran allows using BOZ literal constants outside
1783 DATA statements and the four intrinsic functions allowed by Fortran 2003.
1784 In DATA statements, in direct assignments, where the right-hand side
1785 only contains a BOZ literal constant, and for old-style initializers of
1786 the form @code{integer i /o'0173'/}, the constant is transferred
1787 as if @code{TRANSFER} had been used; for @code{COMPLEX} numbers, only
1788 the real part is initialized unless @code{CMPLX} is used. In all other
1789 cases, the BOZ literal constant is converted to an @code{INTEGER} value with
1790 the largest decimal representation. This value is then converted
1791 numerically to the type and kind of the variable in question.
1792 (For instance, @code{real :: r = b'0000001' + 1} initializes @code{r}
1793 with @code{2.0}.) As different compilers implement the extension
1794 differently, one should be careful when doing bitwise initialization
1795 of non-integer variables.
1797 Note that initializing an @code{INTEGER} variable with a statement such
1798 as @code{DATA i/Z'FFFFFFFF'/} will give an integer overflow error rather
1799 than the desired result of @math{-1} when @code{i} is a 32-bit integer
1800 on a system that supports 64-bit integers. The @samp{-fno-range-check}
1801 option can be used as a workaround for legacy code that initializes
1802 integers in this manner.
1804 @node Real array indices
1805 @subsection Real array indices
1806 @cindex array, indices of type real
1808 As an extension, GNU Fortran allows the use of @code{REAL} expressions
1809 or variables as array indices.
1811 @node Unary operators
1812 @subsection Unary operators
1813 @cindex operators, unary
1815 As an extension, GNU Fortran allows unary plus and unary minus operators
1816 to appear as the second operand of binary arithmetic operators without
1817 the need for parenthesis.
1823 @node Implicitly convert LOGICAL and INTEGER values
1824 @subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values
1825 @cindex conversion, to integer
1826 @cindex conversion, to logical
1828 As an extension for backwards compatibility with other compilers, GNU
1829 Fortran allows the implicit conversion of @code{LOGICAL} values to
1830 @code{INTEGER} values and vice versa. When converting from a
1831 @code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as
1832 zero, and @code{.TRUE.} is interpreted as one. When converting from
1833 @code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as
1834 @code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}.
1845 However, there is no implicit conversion of @code{INTEGER} values in
1846 @code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values
1849 @node Hollerith constants support
1850 @subsection Hollerith constants support
1851 @cindex Hollerith constants
1853 GNU Fortran supports Hollerith constants in assignments, function
1854 arguments, and @code{DATA} and @code{ASSIGN} statements. A Hollerith
1855 constant is written as a string of characters preceded by an integer
1856 constant indicating the character count, and the letter @code{H} or
1857 @code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER},
1858 @code{REAL}, or @code{complex}) or @code{LOGICAL} variable. The
1859 constant will be padded or truncated to fit the size of the variable in
1862 Examples of valid uses of Hollerith constants:
1865 data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/
1866 x(1) = 16HABCDEFGHIJKLMNOP
1870 Invalid Hollerith constants examples:
1873 a = 8H12345678 ! Valid, but the Hollerith constant will be truncated.
1874 a = 0H ! At least one character is needed.
1877 In general, Hollerith constants were used to provide a rudimentary
1878 facility for handling character strings in early Fortran compilers,
1879 prior to the introduction of @code{CHARACTER} variables in Fortran 77;
1880 in those cases, the standard-compliant equivalent is to convert the
1881 program to use proper character strings. On occasion, there may be a
1882 case where the intent is specifically to initialize a numeric variable
1883 with a given byte sequence. In these cases, the same result can be
1884 obtained by using the @code{TRANSFER} statement, as in this example.
1886 INTEGER(KIND=4) :: a
1887 a = TRANSFER ("abcd", a) ! equivalent to: a = 4Habcd
1892 @subsection Cray pointers
1893 @cindex pointer, Cray
1895 Cray pointers are part of a non-standard extension that provides a
1896 C-like pointer in Fortran. This is accomplished through a pair of
1897 variables: an integer "pointer" that holds a memory address, and a
1898 "pointee" that is used to dereference the pointer.
1900 Pointer/pointee pairs are declared in statements of the form:
1902 pointer ( <pointer> , <pointee> )
1906 pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ...
1908 The pointer is an integer that is intended to hold a memory address.
1909 The pointee may be an array or scalar.
1910 If an assumed-size array is permitted within the scoping unit, a
1911 pointee can be an assumed-size array.
1912 That is, the last dimension may be left unspecified by using a @code{*}
1913 in place of a value. A pointee cannot be an assumed shape array.
1914 No space is allocated for the pointee.
1916 The pointee may have its type declared before or after the pointer
1917 statement, and its array specification (if any) may be declared
1918 before, during, or after the pointer statement. The pointer may be
1919 declared as an integer prior to the pointer statement. However, some
1920 machines have default integer sizes that are different than the size
1921 of a pointer, and so the following code is not portable:
1926 If a pointer is declared with a kind that is too small, the compiler
1927 will issue a warning; the resulting binary will probably not work
1928 correctly, because the memory addresses stored in the pointers may be
1929 truncated. It is safer to omit the first line of the above example;
1930 if explicit declaration of ipt's type is omitted, then the compiler
1931 will ensure that ipt is an integer variable large enough to hold a
1934 Pointer arithmetic is valid with Cray pointers, but it is not the same
1935 as C pointer arithmetic. Cray pointers are just ordinary integers, so
1936 the user is responsible for determining how many bytes to add to a
1937 pointer in order to increment it. Consider the following example:
1941 pointer (ipt, pointee)
1945 The last statement does not set @code{ipt} to the address of
1946 @code{target(1)}, as it would in C pointer arithmetic. Adding @code{1}
1947 to @code{ipt} just adds one byte to the address stored in @code{ipt}.
1949 Any expression involving the pointee will be translated to use the
1950 value stored in the pointer as the base address.
1952 To get the address of elements, this extension provides an intrinsic
1953 function @code{LOC()}. The @code{LOC()} function is equivalent to the
1954 @code{&} operator in C, except the address is cast to an integer type:
1957 pointer(ipt, arpte(10))
1959 ipt = loc(ar) ! Makes arpte is an alias for ar
1960 arpte(1) = 1.0 ! Sets ar(1) to 1.0
1962 The pointer can also be set by a call to the @code{MALLOC} intrinsic
1965 Cray pointees often are used to alias an existing variable. For
1973 As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for
1974 @code{target}. The optimizer, however, will not detect this aliasing, so
1975 it is unsafe to use @code{iarr} and @code{target} simultaneously. Using
1976 a pointee in any way that violates the Fortran aliasing rules or
1977 assumptions is illegal. It is the user's responsibility to avoid doing
1978 this; the compiler works under the assumption that no such aliasing
1981 Cray pointers will work correctly when there is no aliasing (i.e., when
1982 they are used to access a dynamically allocated block of memory), and
1983 also in any routine where a pointee is used, but any variable with which
1984 it shares storage is not used. Code that violates these rules may not
1985 run as the user intends. This is not a bug in the optimizer; any code
1986 that violates the aliasing rules is illegal. (Note that this is not
1987 unique to GNU Fortran; any Fortran compiler that supports Cray pointers
1988 will ``incorrectly'' optimize code with illegal aliasing.)
1990 There are a number of restrictions on the attributes that can be applied
1991 to Cray pointers and pointees. Pointees may not have the
1992 @code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY},
1993 @code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers
1994 may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET},
1995 @code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor
1996 may they be function results. Pointees may not occur in more than one
1997 pointer statement. A pointee cannot be a pointer. Pointees cannot occur
1998 in equivalence, common, or data statements.
2000 A Cray pointer may also point to a function or a subroutine. For
2001 example, the following excerpt is valid:
2005 pointer (subptr,subpte)
2015 A pointer may be modified during the course of a program, and this
2016 will change the location to which the pointee refers. However, when
2017 pointees are passed as arguments, they are treated as ordinary
2018 variables in the invoked function. Subsequent changes to the pointer
2019 will not change the base address of the array that was passed.
2021 @node CONVERT specifier
2022 @subsection @code{CONVERT} specifier
2023 @cindex @code{CONVERT} specifier
2025 GNU Fortran allows the conversion of unformatted data between little-
2026 and big-endian representation to facilitate moving of data
2027 between different systems. The conversion can be indicated with
2028 the @code{CONVERT} specifier on the @code{OPEN} statement.
2029 @xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying
2030 the data format via an environment variable.
2032 Valid values for @code{CONVERT} are:
2034 @item @code{CONVERT='NATIVE'} Use the native format. This is the default.
2035 @item @code{CONVERT='SWAP'} Swap between little- and big-endian.
2036 @item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation
2037 for unformatted files.
2038 @item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for
2042 Using the option could look like this:
2044 open(file='big.dat',form='unformatted',access='sequential', &
2045 convert='big_endian')
2048 The value of the conversion can be queried by using
2049 @code{INQUIRE(CONVERT=ch)}. The values returned are
2050 @code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}.
2052 @code{CONVERT} works between big- and little-endian for
2053 @code{INTEGER} values of all supported kinds and for @code{REAL}
2054 on IEEE systems of kinds 4 and 8. Conversion between different
2055 ``extended double'' types on different architectures such as
2056 m68k and x86_64, which GNU Fortran
2057 supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will
2060 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
2061 environment variable will override the CONVERT specifier in the
2062 open statement}. This is to give control over data formats to
2063 users who do not have the source code of their program available.
2065 Using anything but the native representation for unformatted data
2066 carries a significant speed overhead. If speed in this area matters
2067 to you, it is best if you use this only for data that needs to be
2074 OpenMP (Open Multi-Processing) is an application programming
2075 interface (API) that supports multi-platform shared memory
2076 multiprocessing programming in C/C++ and Fortran on many
2077 architectures, including Unix and Microsoft Windows platforms.
2078 It consists of a set of compiler directives, library routines,
2079 and environment variables that influence run-time behavior.
2081 GNU Fortran strives to be compatible to the
2082 @uref{http://openmp.org/wp/openmp-specifications/,
2083 OpenMP Application Program Interface v4.5}.
2085 To enable the processing of the OpenMP directive @code{!$omp} in
2086 free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp}
2087 directives in fixed form; the @code{!$} conditional compilation sentinels
2088 in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels
2089 in fixed form, @command{gfortran} needs to be invoked with the
2090 @option{-fopenmp}. This also arranges for automatic linking of the
2091 GNU Offloading and Multi Processing Runtime Library
2092 @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
2095 The OpenMP Fortran runtime library routines are provided both in a
2096 form of a Fortran 90 module named @code{omp_lib} and in a form of
2097 a Fortran @code{include} file named @file{omp_lib.h}.
2099 An example of a parallelized loop taken from Appendix A.1 of
2100 the OpenMP Application Program Interface v2.5:
2102 SUBROUTINE A1(N, A, B)
2105 !$OMP PARALLEL DO !I is private by default
2107 B(I) = (A(I) + A(I-1)) / 2.0
2109 !$OMP END PARALLEL DO
2116 @option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays
2117 will be allocated on the stack. When porting existing code to OpenMP,
2118 this may lead to surprising results, especially to segmentation faults
2119 if the stacksize is limited.
2122 On glibc-based systems, OpenMP enabled applications cannot be statically
2123 linked due to limitations of the underlying pthreads-implementation. It
2124 might be possible to get a working solution if
2125 @command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added
2126 to the command line. However, this is not supported by @command{gcc} and
2127 thus not recommended.
2134 OpenACC is an application programming interface (API) that supports
2135 offloading of code to accelerator devices. It consists of a set of
2136 compiler directives, library routines, and environment variables that
2137 influence run-time behavior.
2139 GNU Fortran strives to be compatible to the
2140 @uref{http://www.openacc.org/, OpenACC Application Programming
2143 To enable the processing of the OpenACC directive @code{!$acc} in
2144 free-form source code; the @code{c$acc}, @code{*$acc} and @code{!$acc}
2145 directives in fixed form; the @code{!$} conditional compilation
2146 sentinels in free form; and the @code{c$}, @code{*$} and @code{!$}
2147 sentinels in fixed form, @command{gfortran} needs to be invoked with
2148 the @option{-fopenacc}. This also arranges for automatic linking of
2149 the GNU Offloading and Multi Processing Runtime Library
2150 @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
2153 The OpenACC Fortran runtime library routines are provided both in a
2154 form of a Fortran 90 module named @code{openacc} and in a form of a
2155 Fortran @code{include} file named @file{openacc_lib.h}.
2157 Note that this is an experimental feature, incomplete, and subject to
2158 change in future versions of GCC. See
2159 @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
2161 @node Argument list functions
2162 @subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC}
2163 @cindex argument list functions
2168 GNU Fortran supports argument list functions @code{%VAL}, @code{%REF}
2169 and @code{%LOC} statements, for backward compatibility with g77.
2170 It is recommended that these should be used only for code that is
2171 accessing facilities outside of GNU Fortran, such as operating system
2172 or windowing facilities. It is best to constrain such uses to isolated
2173 portions of a program--portions that deal specifically and exclusively
2174 with low-level, system-dependent facilities. Such portions might well
2175 provide a portable interface for use by the program as a whole, but are
2176 themselves not portable, and should be thoroughly tested each time they
2177 are rebuilt using a new compiler or version of a compiler.
2179 @code{%VAL} passes a scalar argument by value, @code{%REF} passes it by
2180 reference and @code{%LOC} passes its memory location. Since gfortran
2181 already passes scalar arguments by reference, @code{%REF} is in effect
2182 a do-nothing. @code{%LOC} has the same effect as a Fortran pointer.
2184 An example of passing an argument by value to a C subroutine foo.:
2187 C prototype void foo_ (float x);
2196 For details refer to the g77 manual
2197 @uref{https://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}.
2199 Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the
2200 GNU Fortran testsuite are worth a look.
2202 @node Read/Write after EOF marker
2203 @subsection Read/Write after EOF marker
2205 @cindex @code{BACKSPACE}
2206 @cindex @code{REWIND}
2208 Some legacy codes rely on allowing @code{READ} or @code{WRITE} after the
2209 EOF file marker in order to find the end of a file. GNU Fortran normally
2210 rejects these codes with a run-time error message and suggests the user
2211 consider @code{BACKSPACE} or @code{REWIND} to properly position
2212 the file before the EOF marker. As an extension, the run-time error may
2213 be disabled using -std=legacy.
2216 @node STRUCTURE and RECORD
2217 @subsection @code{STRUCTURE} and @code{RECORD}
2218 @cindex @code{STRUCTURE}
2219 @cindex @code{RECORD}
2221 Record structures are a pre-Fortran-90 vendor extension to create
2222 user-defined aggregate data types. Support for record structures in GNU
2223 Fortran can be enabled with the @option{-fdec-structure} compile flag.
2224 If you have a choice, you should instead use Fortran 90's ``derived types'',
2225 which have a different syntax.
2227 In many cases, record structures can easily be converted to derived types.
2228 To convert, replace @code{STRUCTURE /}@var{structure-name}@code{/}
2229 by @code{TYPE} @var{type-name}. Additionally, replace
2230 @code{RECORD /}@var{structure-name}@code{/} by
2231 @code{TYPE(}@var{type-name}@code{)}. Finally, in the component access,
2232 replace the period (@code{.}) by the percent sign (@code{%}).
2234 Here is an example of code using the non portable record structure syntax:
2237 ! Declaring a structure named ``item'' and containing three fields:
2238 ! an integer ID, an description string and a floating-point price.
2241 CHARACTER(LEN=200) description
2245 ! Define two variables, an single record of type ``item''
2246 ! named ``pear'', and an array of items named ``store_catalog''
2247 RECORD /item/ pear, store_catalog(100)
2249 ! We can directly access the fields of both variables
2251 pear.description = "juicy D'Anjou pear"
2253 store_catalog(7).id = 7831
2254 store_catalog(7).description = "milk bottle"
2255 store_catalog(7).price = 1.2
2257 ! We can also manipulate the whole structure
2258 store_catalog(12) = pear
2259 print *, store_catalog(12)
2263 This code can easily be rewritten in the Fortran 90 syntax as following:
2266 ! ``STRUCTURE /name/ ... END STRUCTURE'' becomes
2267 ! ``TYPE name ... END TYPE''
2270 CHARACTER(LEN=200) description
2274 ! ``RECORD /name/ variable'' becomes ``TYPE(name) variable''
2275 TYPE(item) pear, store_catalog(100)
2277 ! Instead of using a dot (.) to access fields of a record, the
2278 ! standard syntax uses a percent sign (%)
2280 pear%description = "juicy D'Anjou pear"
2282 store_catalog(7)%id = 7831
2283 store_catalog(7)%description = "milk bottle"
2284 store_catalog(7)%price = 1.2
2286 ! Assignments of a whole variable do not change
2287 store_catalog(12) = pear
2288 print *, store_catalog(12)
2292 GNU Fortran implements STRUCTURES like derived types with the following
2293 rules and exceptions:
2296 @item Structures act like derived types with the @code{SEQUENCE} attribute.
2297 Otherwise they may contain no specifiers.
2299 @item Structures may contain a special field with the name @code{%FILL}.
2300 This will create an anonymous component which cannot be accessed but occupies
2301 space just as if a component of the same type was declared in its place, useful
2302 for alignment purposes. As an example, the following structure will consist
2303 of at least sixteen bytes:
2313 @item Structures may share names with other symbols. For example, the following
2314 is invalid for derived types, but valid for structures:
2320 record /header/ header
2323 @item Structure types may be declared nested within another parent structure.
2326 structure /type-name/
2328 structure [/<type-name>/] <field-list>
2332 The type name may be ommitted, in which case the structure type itself is
2333 anonymous, and other structures of the same type cannot be instantiated. The
2334 following shows some examples:
2337 structure /appointment/
2338 ! nested structure definition: app_time is an array of two 'time'
2339 structure /time/ app_time (2)
2340 integer(1) hour, minute
2345 ! The 'time' structure is still usable
2351 structure /appointment/
2352 ! anonymous nested structure definition
2353 structure start, end
2354 integer(1) hour, minute
2360 @item Structures may contain @code{UNION} blocks. For more detail see the
2361 section on @ref{UNION and MAP}.
2363 @item Structures support old-style initialization of components, like
2364 those described in @ref{Old-style variable initialization}. For array
2365 initializers, an initializer may contain a repeat specification of the form
2366 @code{<literal-integer> * <constant-initializer>}. The value of the integer
2367 indicates the number of times to repeat the constant initializer when expanding
2368 the initializer list.
2372 @subsection @code{UNION} and @code{MAP}
2373 @cindex @code{UNION}
2376 Unions are an old vendor extension which were commonly used with the
2377 non-standard @ref{STRUCTURE and RECORD} extensions. Use of @code{UNION} and
2378 @code{MAP} is automatically enabled with @option{-fdec-structure}.
2380 A @code{UNION} declaration occurs within a structure; within the definition of
2381 each union is a number of @code{MAP} blocks. Each @code{MAP} shares storage
2382 with its sibling maps (in the same union), and the size of the union is the
2383 size of the largest map within it, just as with unions in C. The major
2384 difference is that component references do not indicate which union or map the
2385 component is in (the compiler gets to figure that out).
2387 Here is a small example:
2392 character(2) w0, w1, w2
2400 record /myunion/ rec
2401 ! After this assignment...
2404 ! The following is true:
2410 The two maps share memory, and the size of the union is ultimately six bytes:
2413 0 1 2 3 4 5 6 Byte offset
2414 -------------------------------
2416 -------------------------------
2419 \-------/ \-------/ \-------/
2422 \---------------------------/
2425 Following is an example mirroring the layout of an Intel x86_64 register:
2434 character(8) rh ! rah
2437 character(8) rl ! ral
2440 character(8) ex ! eax
2443 character(4) eh ! eah
2446 character(4) el ! eal
2463 ! After this assignment...
2464 a.rx = 'AAAAAAAA.BBB.C.D'
2466 ! The following is true:
2467 a.rx === 'AAAAAAAA.BBB.C.D'
2478 @node Type variants for integer intrinsics
2479 @subsection Type variants for integer intrinsics
2480 @cindex intrinsics, integer
2482 Similar to the D/C prefixes to real functions to specify the input/output
2483 types, GNU Fortran offers B/I/J/K prefixes to integer functions for
2484 compatibility with DEC programs. The types implied by each are:
2487 @code{B} - @code{INTEGER(kind=1)}
2488 @code{I} - @code{INTEGER(kind=2)}
2489 @code{J} - @code{INTEGER(kind=4)}
2490 @code{K} - @code{INTEGER(kind=8)}
2493 GNU Fortran supports these with the flag @option{-fdec-intrinsic-ints}.
2494 Intrinsics for which prefixed versions are available and in what form are noted
2495 in @ref{Intrinsic Procedures}. The complete list of supported intrinsics is
2498 @multitable @columnfractions .2 .2 .2 .2 .2
2500 @headitem Intrinsic @tab B @tab I @tab J @tab K
2502 @item @code{@ref{ABS}}
2503 @tab @code{BABS} @tab @code{IIABS} @tab @code{JIABS} @tab @code{KIABS}
2504 @item @code{@ref{BTEST}}
2505 @tab @code{BBTEST} @tab @code{BITEST} @tab @code{BJTEST} @tab @code{BKTEST}
2506 @item @code{@ref{IAND}}
2507 @tab @code{BIAND} @tab @code{IIAND} @tab @code{JIAND} @tab @code{KIAND}
2508 @item @code{@ref{IBCLR}}
2509 @tab @code{BBCLR} @tab @code{IIBCLR} @tab @code{JIBCLR} @tab @code{KIBCLR}
2510 @item @code{@ref{IBITS}}
2511 @tab @code{BBITS} @tab @code{IIBITS} @tab @code{JIBITS} @tab @code{KIBITS}
2512 @item @code{@ref{IBSET}}
2513 @tab @code{BBSET} @tab @code{IIBSET} @tab @code{JIBSET} @tab @code{KIBSET}
2514 @item @code{@ref{IEOR}}
2515 @tab @code{BIEOR} @tab @code{IIEOR} @tab @code{JIEOR} @tab @code{KIEOR}
2516 @item @code{@ref{IOR}}
2517 @tab @code{BIOR} @tab @code{IIOR} @tab @code{JIOR} @tab @code{KIOR}
2518 @item @code{@ref{ISHFT}}
2519 @tab @code{BSHFT} @tab @code{IISHFT} @tab @code{JISHFT} @tab @code{KISHFT}
2520 @item @code{@ref{ISHFTC}}
2521 @tab @code{BSHFTC} @tab @code{IISHFTC} @tab @code{JISHFTC} @tab @code{KISHFTC}
2522 @item @code{@ref{MOD}}
2523 @tab @code{BMOD} @tab @code{IMOD} @tab @code{JMOD} @tab @code{KMOD}
2524 @item @code{@ref{NOT}}
2525 @tab @code{BNOT} @tab @code{INOT} @tab @code{JNOT} @tab @code{KNOT}
2526 @item @code{@ref{REAL}}
2527 @tab @code{--} @tab @code{FLOATI} @tab @code{FLOATJ} @tab @code{FLOATK}
2530 @node AUTOMATIC and STATIC attributes
2531 @subsection @code{AUTOMATIC} and @code{STATIC} attributes
2532 @cindex variable attributes
2533 @cindex @code{AUTOMATIC}
2534 @cindex @code{STATIC}
2536 With @option{-fdec-static} GNU Fortran supports the DEC extended attributes
2537 @code{STATIC} and @code{AUTOMATIC} to provide explicit specification of entity
2538 storage. These follow the syntax of the Fortran standard @code{SAVE} attribute.
2540 @code{STATIC} is exactly equivalent to @code{SAVE}, and specifies that
2541 an entity should be allocated in static memory. As an example, @code{STATIC}
2542 local variables will retain their values across multiple calls to a function.
2544 Entities marked @code{AUTOMATIC} will be stack automatic whenever possible.
2545 @code{AUTOMATIC} is the default for local variables smaller than
2546 @option{-fmax-stack-var-size}, unless @option{-fno-automatic} is given. This
2547 attribute overrides @option{-fno-automatic}, @option{-fmax-stack-var-size}, and
2548 blanket @code{SAVE} statements.
2555 integer, automatic :: i ! automatic variable
2556 integer x, y ! static variables
2563 integer a, b, c, x, y, z
2567 ! a, b, c, and z are automatic
2568 ! x and y are static
2572 ! Compiled with -fno-automatic
2576 ! a is automatic; b, c, and d are static
2580 @node Extended math intrinsics
2581 @subsection Extended math intrinsics
2582 @cindex intrinsics, math
2583 @cindex intrinsics, trigonometric functions
2585 GNU Fortran supports an extended list of mathematical intrinsics with the
2586 compile flag @option{-fdec-math} for compatability with legacy code.
2587 These intrinsics are described fully in @ref{Intrinsic Procedures} where it is
2588 noted that they are extensions and should be avoided whenever possible.
2590 Specifically, @option{-fdec-math} enables the @ref{COTAN} intrinsic, and
2591 trigonometric intrinsics which accept or produce values in degrees instead of
2592 radians. Here is a summary of the new intrinsics:
2594 @multitable @columnfractions .5 .5
2595 @headitem Radians @tab Degrees
2596 @item @code{@ref{ACOS}} @tab @code{@ref{ACOSD}}*
2597 @item @code{@ref{ASIN}} @tab @code{@ref{ASIND}}*
2598 @item @code{@ref{ATAN}} @tab @code{@ref{ATAND}}*
2599 @item @code{@ref{ATAN2}} @tab @code{@ref{ATAN2D}}*
2600 @item @code{@ref{COS}} @tab @code{@ref{COSD}}*
2601 @item @code{@ref{COTAN}}* @tab @code{@ref{COTAND}}*
2602 @item @code{@ref{SIN}} @tab @code{@ref{SIND}}*
2603 @item @code{@ref{TAN}} @tab @code{@ref{TAND}}*
2606 * Enabled with @option{-fdec-math}.
2608 For advanced users, it may be important to know the implementation of these
2609 functions. They are simply wrappers around the standard radian functions, which
2610 have more accurate builtin versions. These functions convert their arguments
2611 (or results) to degrees (or radians) by taking the value modulus 360 (or 2*pi)
2612 and then multiplying it by a constant radian-to-degree (or degree-to-radian)
2613 factor, as appropriate. The factor is computed at compile-time as 180/pi (or
2616 @node Form feed as whitespace
2617 @subsection Form feed as whitespace
2618 @cindex form feed whitespace
2620 Historically, legacy compilers allowed insertion of form feed characters ('\f',
2621 ASCII 0xC) at the beginning of lines for formatted output to line printers,
2622 though the Fortran standard does not mention this. GNU Fortran supports the
2623 interpretation of form feed characters in source as whitespace for
2626 @node TYPE as an alias for PRINT
2627 @subsection TYPE as an alias for PRINT
2628 @cindex type alias print
2629 For compatibility, GNU Fortran will interpret @code{TYPE} statements as
2630 @code{PRINT} statements with the flag @option{-fdec}. With this flag asserted,
2631 the following two examples are equivalent:
2634 TYPE *, 'hello world'
2638 PRINT *, 'hello world'
2641 @node %LOC as an rvalue
2642 @subsection %LOC as an rvalue
2644 Normally @code{%LOC} is allowed only in parameter lists. However the intrinsic
2645 function @code{LOC} does the same thing, and is usable as the right-hand-side of
2646 assignments. For compatibility, GNU Fortran supports the use of @code{%LOC} as
2647 an alias for the builtin @code{LOC} with @option{-std=legacy}. With this
2648 feature enabled the following two examples are equivalent:
2661 @node .XOR. operator
2662 @subsection .XOR. operator
2663 @cindex operators, xor
2665 GNU Fortran supports @code{.XOR.} as a logical operator with @code{-std=legacy}
2666 for compatibility with legacy code. @code{.XOR.} is equivalent to
2667 @code{.NEQV.}. That is, the output is true if and only if the inputs differ.
2669 @node Bitwise logical operators
2670 @subsection Bitwise logical operators
2671 @cindex logical, bitwise
2673 With @option{-fdec}, GNU Fortran relaxes the type constraints on
2674 logical operators to allow integer operands, and performs the corresponding
2675 bitwise operation instead. This flag is for compatibility only, and should be
2676 avoided in new code. Consider:
2685 In this example, compiled with @option{-fdec}, GNU Fortran will
2686 replace the @code{.AND.} operation with a call to the intrinsic
2687 @code{@ref{IAND}} function, yielding the bitwise-and of @code{i} and @code{j}.
2689 Note that this conversion will occur if at least one operand is of integral
2690 type. As a result, a logical operand will be converted to an integer when the
2691 other operand is an integer in a logical operation. In this case,
2692 @code{.TRUE.} is converted to @code{1} and @code{.FALSE.} to @code{0}.
2694 Here is the mapping of logical operator to bitwise intrinsic used with
2697 @multitable @columnfractions .25 .25 .5
2698 @headitem Operator @tab Intrinsic @tab Bitwise operation
2699 @item @code{.NOT.} @tab @code{@ref{NOT}} @tab complement
2700 @item @code{.AND.} @tab @code{@ref{IAND}} @tab intersection
2701 @item @code{.OR.} @tab @code{@ref{IOR}} @tab union
2702 @item @code{.NEQV.} @tab @code{@ref{IEOR}} @tab exclusive or
2703 @item @code{.EQV.} @tab @code{@ref{NOT}(@ref{IEOR})} @tab complement of exclusive or
2706 @node Extended I/O specifiers
2707 @subsection Extended I/O specifiers
2708 @cindex @code{CARRIAGECONTROL}
2709 @cindex @code{READONLY}
2710 @cindex @code{SHARE}
2711 @cindex @code{SHARED}
2712 @cindex @code{NOSHARED}
2713 @cindex I/O specifiers
2715 GNU Fortran supports the additional legacy I/O specifiers
2716 @code{CARRIAGECONTROL}, @code{READONLY}, and @code{SHARE} with the
2717 compile flag @option{-fdec}, for compatibility.
2720 @item CARRIAGECONTROL
2721 The @code{CARRIAGECONTROL} specifier allows a user to control line
2722 termination settings between output records for an I/O unit. The specifier has
2723 no meaning for readonly files. When @code{CARRAIGECONTROL} is specified upon
2724 opening a unit for formatted writing, the exact @code{CARRIAGECONTROL} setting
2725 determines what characters to write between output records. The syntax is:
2728 OPEN(..., CARRIAGECONTROL=cc)
2731 Where @emph{cc} is a character expression that evaluates to one of the
2734 @multitable @columnfractions .2 .8
2735 @item @code{'LIST'} @tab One line feed between records (default)
2736 @item @code{'FORTRAN'} @tab Legacy interpretation of the first character (see below)
2737 @item @code{'NONE'} @tab No separator between records
2740 With @code{CARRIAGECONTROL='FORTRAN'}, when a record is written, the first
2741 character of the input record is not written, and instead determines the output
2742 record separator as follows:
2744 @multitable @columnfractions .3 .3 .4
2745 @headitem Leading character @tab Meaning @tab Output separating character(s)
2746 @item @code{'+'} @tab Overprinting @tab Carriage return only
2747 @item @code{'-'} @tab New line @tab Line feed and carriage return
2748 @item @code{'0'} @tab Skip line @tab Two line feeds and carriage return
2749 @item @code{'1'} @tab New page @tab Form feed and carriage return
2750 @item @code{'$'} @tab Prompting @tab Line feed (no carriage return)
2751 @item @code{CHAR(0)} @tab Overprinting (no advance) @tab None
2755 The @code{READONLY} specifier may be given upon opening a unit, and is
2756 equivalent to specifying @code{ACTION='READ'}, except that the file may not be
2757 deleted on close (i.e. @code{CLOSE} with @code{STATUS="DELETE"}). The syntax
2761 @code{OPEN(..., READONLY)}
2765 The @code{SHARE} specifier allows system-level locking on a unit upon opening
2766 it for controlled access from multiple processes/threads. The @code{SHARE}
2767 specifier has several forms:
2775 Where @emph{sh} in the first form is a character expression that evaluates to
2776 a value as seen in the table below. The latter two forms are aliases
2777 for particular values of @emph{sh}:
2779 @multitable @columnfractions .3 .3 .4
2780 @headitem Explicit form @tab Short form @tab Meaning
2781 @item @code{SHARE='DENYRW'} @tab @code{NOSHARED} @tab Exclusive (write) lock
2782 @item @code{SHARE='DENYNONE'} @tab @code{SHARED} @tab Shared (read) lock
2785 In general only one process may hold an exclusive (write) lock for a given file
2786 at a time, whereas many processes may hold shared (read) locks for the same
2789 The behavior of locking may vary with your operating system. On POSIX systems,
2790 locking is implemented with @code{fcntl}. Consult your corresponding operating
2791 system's manual pages for further details. Locking via @code{SHARE=} is not
2792 supported on other systems.
2796 @node Legacy PARAMETER statements
2797 @subsection Legacy PARAMETER statements
2800 For compatibility, GNU Fortran supports legacy PARAMETER statements without
2801 parentheses with @option{-std=legacy}. A warning is emitted if used with
2802 @option{-std=gnu}, and an error is acknowledged with a real Fortran standard
2803 flag (@option{-std=f95}, etc...). These statements take the following form:
2807 parameter e = 2.718282
2812 @node Default exponents
2813 @subsection Default exponents
2816 For compatibility, GNU Fortran supports a default exponent of zero in real
2817 constants with @option{-fdec}. For example, @code{9e} would be
2818 interpreted as @code{9e0}, rather than an error.
2821 @node Extensions not implemented in GNU Fortran
2822 @section Extensions not implemented in GNU Fortran
2823 @cindex extensions, not implemented
2825 The long history of the Fortran language, its wide use and broad
2826 userbase, the large number of different compiler vendors and the lack of
2827 some features crucial to users in the first standards have lead to the
2828 existence of a number of important extensions to the language. While
2829 some of the most useful or popular extensions are supported by the GNU
2830 Fortran compiler, not all existing extensions are supported. This section
2831 aims at listing these extensions and offering advice on how best make
2832 code that uses them running with the GNU Fortran compiler.
2834 @c More can be found here:
2835 @c -- https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html
2836 @c -- the list of Fortran and libgfortran bugs closed as WONTFIX:
2837 @c http://tinyurl.com/2u4h5y
2840 * ENCODE and DECODE statements::
2841 * Variable FORMAT expressions::
2842 @c * Q edit descriptor::
2843 @c * TYPE and ACCEPT I/O Statements::
2844 @c * DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers::
2845 @c * Omitted arguments in procedure call::
2846 * Alternate complex function syntax::
2847 * Volatile COMMON blocks::
2848 * OPEN( ... NAME=)::
2851 @node ENCODE and DECODE statements
2852 @subsection @code{ENCODE} and @code{DECODE} statements
2853 @cindex @code{ENCODE}
2854 @cindex @code{DECODE}
2856 GNU Fortran does not support the @code{ENCODE} and @code{DECODE}
2857 statements. These statements are best replaced by @code{READ} and
2858 @code{WRITE} statements involving internal files (@code{CHARACTER}
2859 variables and arrays), which have been part of the Fortran standard since
2860 Fortran 77. For example, replace a code fragment like
2865 c ... Code that sets LINE
2866 DECODE (80, 9000, LINE) A, B, C
2867 9000 FORMAT (1X, 3(F10.5))
2874 CHARACTER(LEN=80) LINE
2876 c ... Code that sets LINE
2877 READ (UNIT=LINE, FMT=9000) A, B, C
2878 9000 FORMAT (1X, 3(F10.5))
2881 Similarly, replace a code fragment like
2886 c ... Code that sets A, B and C
2887 ENCODE (80, 9000, LINE) A, B, C
2888 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2895 CHARACTER(LEN=80) LINE
2897 c ... Code that sets A, B and C
2898 WRITE (UNIT=LINE, FMT=9000) A, B, C
2899 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2903 @node Variable FORMAT expressions
2904 @subsection Variable @code{FORMAT} expressions
2905 @cindex @code{FORMAT}
2907 A variable @code{FORMAT} expression is format statement which includes
2908 angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU
2909 Fortran does not support this legacy extension. The effect of variable
2910 format expressions can be reproduced by using the more powerful (and
2911 standard) combination of internal output and string formats. For example,
2912 replace a code fragment like this:
2923 c Variable declaration
2924 CHARACTER(LEN=20) FMT
2926 c Other code here...
2928 WRITE(FMT,'("(I", I0, ")")') N+1
2936 c Variable declaration
2937 CHARACTER(LEN=20) FMT
2939 c Other code here...
2942 WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1
2946 @node Alternate complex function syntax
2947 @subsection Alternate complex function syntax
2948 @cindex Complex function
2950 Some Fortran compilers, including @command{g77}, let the user declare
2951 complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as
2952 well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy
2953 extensions. @command{gfortran} accepts the latter form, which is more
2954 common, but not the former.
2957 @node Volatile COMMON blocks
2958 @subsection Volatile @code{COMMON} blocks
2959 @cindex @code{VOLATILE}
2960 @cindex @code{COMMON}
2962 Some Fortran compilers, including @command{g77}, let the user declare
2963 @code{COMMON} with the @code{VOLATILE} attribute. This is
2964 invalid standard Fortran syntax and is not supported by
2965 @command{gfortran}. Note that @command{gfortran} accepts
2966 @code{VOLATILE} variables in @code{COMMON} blocks since revision 4.3.
2969 @node OPEN( ... NAME=)
2970 @subsection @code{OPEN( ... NAME=)}
2973 Some Fortran compilers, including @command{g77}, let the user declare
2974 @code{OPEN( ... NAME=)}. This is
2975 invalid standard Fortran syntax and is not supported by
2976 @command{gfortran}. @code{OPEN( ... NAME=)} should be replaced
2977 with @code{OPEN( ... FILE=)}.
2981 @c ---------------------------------------------------------------------
2982 @c ---------------------------------------------------------------------
2983 @c Mixed-Language Programming
2984 @c ---------------------------------------------------------------------
2986 @node Mixed-Language Programming
2987 @chapter Mixed-Language Programming
2988 @cindex Interoperability
2989 @cindex Mixed-language programming
2992 * Interoperability with C::
2993 * GNU Fortran Compiler Directives::
2994 * Non-Fortran Main Program::
2995 * Naming and argument-passing conventions::
2998 This chapter is about mixed-language interoperability, but also applies
2999 if one links Fortran code compiled by different compilers. In most cases,
3000 use of the C Binding features of the Fortran 2003 standard is sufficient,
3001 and their use is highly recommended.
3004 @node Interoperability with C
3005 @section Interoperability with C
3009 * Derived Types and struct::
3010 * Interoperable Global Variables::
3011 * Interoperable Subroutines and Functions::
3012 * Working with Pointers::
3013 * Further Interoperability of Fortran with C::
3016 Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a
3017 standardized way to generate procedure and derived-type
3018 declarations and global variables which are interoperable with C
3019 (ISO/IEC 9899:1999). The @code{bind(C)} attribute has been added
3020 to inform the compiler that a symbol shall be interoperable with C;
3021 also, some constraints are added. Note, however, that not
3022 all C features have a Fortran equivalent or vice versa. For instance,
3023 neither C's unsigned integers nor C's functions with variable number
3024 of arguments have an equivalent in Fortran.
3026 Note that array dimensions are reversely ordered in C and that arrays in
3027 C always start with index 0 while in Fortran they start by default with
3028 1. Thus, an array declaration @code{A(n,m)} in Fortran matches
3029 @code{A[m][n]} in C and accessing the element @code{A(i,j)} matches
3030 @code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]};
3031 assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}).
3033 @node Intrinsic Types
3034 @subsection Intrinsic Types
3036 In order to ensure that exactly the same variable type and kind is used
3037 in C and Fortran, the named constants shall be used which are defined in the
3038 @code{ISO_C_BINDING} intrinsic module. That module contains named constants
3039 for kind parameters and character named constants for the escape sequences
3040 in C. For a list of the constants, see @ref{ISO_C_BINDING}.
3042 For logical types, please note that the Fortran standard only guarantees
3043 interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
3044 logicals and C99 defines that @code{true} has the value 1 and @code{false}
3045 the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL}
3046 (with any kind parameter) gives an undefined result. (Passing other integer
3047 values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the
3048 integer is explicitly or implicitly casted to @code{_Bool}.)
3052 @node Derived Types and struct
3053 @subsection Derived Types and struct
3055 For compatibility of derived types with @code{struct}, one needs to use
3056 the @code{BIND(C)} attribute in the type declaration. For instance, the
3057 following type declaration
3061 TYPE, BIND(C) :: myType
3062 INTEGER(C_INT) :: i1, i2
3063 INTEGER(C_SIGNED_CHAR) :: i3
3064 REAL(C_DOUBLE) :: d1
3065 COMPLEX(C_FLOAT_COMPLEX) :: c1
3066 CHARACTER(KIND=C_CHAR) :: str(5)
3070 matches the following @code{struct} declaration in C
3075 /* Note: "char" might be signed or unsigned. */
3083 Derived types with the C binding attribute shall not have the @code{sequence}
3084 attribute, type parameters, the @code{extends} attribute, nor type-bound
3085 procedures. Every component must be of interoperable type and kind and may not
3086 have the @code{pointer} or @code{allocatable} attribute. The names of the
3087 components are irrelevant for interoperability.
3089 As there exist no direct Fortran equivalents, neither unions nor structs
3090 with bit field or variable-length array members are interoperable.
3092 @node Interoperable Global Variables
3093 @subsection Interoperable Global Variables
3095 Variables can be made accessible from C using the C binding attribute,
3096 optionally together with specifying a binding name. Those variables
3097 have to be declared in the declaration part of a @code{MODULE},
3098 be of interoperable type, and have neither the @code{pointer} nor
3099 the @code{allocatable} attribute.
3105 integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag
3106 type(myType), bind(C) :: tp
3110 Here, @code{_MyProject_flags} is the case-sensitive name of the variable
3111 as seen from C programs while @code{global_flag} is the case-insensitive
3112 name as seen from Fortran. If no binding name is specified, as for
3113 @var{tp}, the C binding name is the (lowercase) Fortran binding name.
3114 If a binding name is specified, only a single variable may be after the
3115 double colon. Note of warning: You cannot use a global variable to
3116 access @var{errno} of the C library as the C standard allows it to be
3117 a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead.
3119 @node Interoperable Subroutines and Functions
3120 @subsection Interoperable Subroutines and Functions
3122 Subroutines and functions have to have the @code{BIND(C)} attribute to
3123 be compatible with C. The dummy argument declaration is relatively
3124 straightforward. However, one needs to be careful because C uses
3125 call-by-value by default while Fortran behaves usually similar to
3126 call-by-reference. Furthermore, strings and pointers are handled
3127 differently. Note that in Fortran 2003 and 2008 only explicit size
3128 and assumed-size arrays are supported but not assumed-shape or
3129 deferred-shape (i.e. allocatable or pointer) arrays. However, those
3130 are allowed since the Technical Specification 29113, see
3131 @ref{Further Interoperability of Fortran with C}
3133 To pass a variable by value, use the @code{VALUE} attribute.
3134 Thus, the following C prototype
3137 @code{int func(int i, int *j)}
3140 matches the Fortran declaration
3143 integer(c_int) function func(i,j)
3144 use iso_c_binding, only: c_int
3145 integer(c_int), VALUE :: i
3149 Note that pointer arguments also frequently need the @code{VALUE} attribute,
3150 see @ref{Working with Pointers}.
3152 Strings are handled quite differently in C and Fortran. In C a string
3153 is a @code{NUL}-terminated array of characters while in Fortran each string
3154 has a length associated with it and is thus not terminated (by e.g.
3155 @code{NUL}). For example, if one wants to use the following C function,
3159 void print_C(char *string) /* equivalent: char string[] */
3161 printf("%s\n", string);
3165 to print ``Hello World'' from Fortran, one can call it using
3168 use iso_c_binding, only: C_CHAR, C_NULL_CHAR
3170 subroutine print_c(string) bind(C, name="print_C")
3171 use iso_c_binding, only: c_char
3172 character(kind=c_char) :: string(*)
3173 end subroutine print_c
3175 call print_c(C_CHAR_"Hello World"//C_NULL_CHAR)
3178 As the example shows, one needs to ensure that the
3179 string is @code{NUL} terminated. Additionally, the dummy argument
3180 @var{string} of @code{print_C} is a length-one assumed-size
3181 array; using @code{character(len=*)} is not allowed. The example
3182 above uses @code{c_char_"Hello World"} to ensure the string
3183 literal has the right type; typically the default character
3184 kind and @code{c_char} are the same and thus @code{"Hello World"}
3185 is equivalent. However, the standard does not guarantee this.
3187 The use of strings is now further illustrated using the C library
3188 function @code{strncpy}, whose prototype is
3191 char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
3194 The function @code{strncpy} copies at most @var{n} characters from
3195 string @var{s2} to @var{s1} and returns @var{s1}. In the following
3196 example, we ignore the return value:
3201 character(len=30) :: str,str2
3203 ! Ignore the return value of strncpy -> subroutine
3204 ! "restrict" is always assumed if we do not pass a pointer
3205 subroutine strncpy(dest, src, n) bind(C)
3207 character(kind=c_char), intent(out) :: dest(*)
3208 character(kind=c_char), intent(in) :: src(*)
3209 integer(c_size_t), value, intent(in) :: n
3210 end subroutine strncpy
3212 str = repeat('X',30) ! Initialize whole string with 'X'
3213 call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, &
3214 len(c_char_"Hello World",kind=c_size_t))
3215 print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX"
3219 The intrinsic procedures are described in @ref{Intrinsic Procedures}.
3221 @node Working with Pointers
3222 @subsection Working with Pointers
3224 C pointers are represented in Fortran via the special opaque derived type
3225 @code{type(c_ptr)} (with private components). Thus one needs to
3226 use intrinsic conversion procedures to convert from or to C pointers.
3228 For some applications, using an assumed type (@code{TYPE(*)}) can be an
3229 alternative to a C pointer; see
3230 @ref{Further Interoperability of Fortran with C}.
3236 type(c_ptr) :: cptr1, cptr2
3237 integer, target :: array(7), scalar
3238 integer, pointer :: pa(:), ps
3239 cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the
3240 ! array is contiguous if required by the C
3242 cptr2 = c_loc(scalar)
3243 call c_f_pointer(cptr2, ps)
3244 call c_f_pointer(cptr2, pa, shape=[7])
3247 When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument
3250 If a pointer is a dummy-argument of an interoperable procedure, it usually
3251 has to be declared using the @code{VALUE} attribute. @code{void*}
3252 matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone
3253 matches @code{void**}.
3255 Procedure pointers are handled analogously to pointers; the C type is
3256 @code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are
3257 @code{C_F_PROCPOINTER} and @code{C_FUNLOC}.
3259 Let us consider two examples of actually passing a procedure pointer from
3260 C to Fortran and vice versa. Note that these examples are also very
3261 similar to passing ordinary pointers between both languages. First,
3262 consider this code in C:
3265 /* Procedure implemented in Fortran. */
3266 void get_values (void (*)(double));
3268 /* Call-back routine we want called from Fortran. */
3272 printf ("Number is %f.\n", x);
3275 /* Call Fortran routine and pass call-back to it. */
3279 get_values (&print_it);
3283 A matching implementation for @code{get_values} in Fortran, that correctly
3284 receives the procedure pointer from C and is able to call it, is given
3285 in the following @code{MODULE}:
3291 ! Define interface of call-back routine.
3293 SUBROUTINE callback (x)
3294 USE, INTRINSIC :: ISO_C_BINDING
3295 REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x
3296 END SUBROUTINE callback
3301 ! Define C-bound procedure.
3302 SUBROUTINE get_values (cproc) BIND(C)
3303 USE, INTRINSIC :: ISO_C_BINDING
3304 TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc
3306 PROCEDURE(callback), POINTER :: proc
3308 ! Convert C to Fortran procedure pointer.
3309 CALL C_F_PROCPOINTER (cproc, proc)
3312 CALL proc (1.0_C_DOUBLE)
3313 CALL proc (-42.0_C_DOUBLE)
3314 CALL proc (18.12_C_DOUBLE)
3315 END SUBROUTINE get_values
3320 Next, we want to call a C routine that expects a procedure pointer argument
3321 and pass it a Fortran procedure (which clearly must be interoperable!).
3322 Again, the C function may be:
3326 call_it (int (*func)(int), int arg)
3332 It can be used as in the following Fortran code:
3336 USE, INTRINSIC :: ISO_C_BINDING
3339 ! Define interface of C function.
3341 INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C)
3342 USE, INTRINSIC :: ISO_C_BINDING
3343 TYPE(C_FUNPTR), INTENT(IN), VALUE :: func
3344 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
3345 END FUNCTION call_it
3350 ! Define procedure passed to C function.
3351 ! It must be interoperable!
3352 INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C)
3353 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
3354 double_it = arg + arg
3355 END FUNCTION double_it
3358 SUBROUTINE foobar ()
3359 TYPE(C_FUNPTR) :: cproc
3360 INTEGER(KIND=C_INT) :: i
3362 ! Get C procedure pointer.
3363 cproc = C_FUNLOC (double_it)
3366 DO i = 1_C_INT, 10_C_INT
3367 PRINT *, call_it (cproc, i)
3369 END SUBROUTINE foobar
3374 @node Further Interoperability of Fortran with C
3375 @subsection Further Interoperability of Fortran with C
3377 The Technical Specification ISO/IEC TS 29113:2012 on further
3378 interoperability of Fortran with C extends the interoperability support
3379 of Fortran 2003 and Fortran 2008. Besides removing some restrictions
3380 and constraints, it adds assumed-type (@code{TYPE(*)}) and assumed-rank
3381 (@code{dimension}) variables and allows for interoperability of
3382 assumed-shape, assumed-rank and deferred-shape arrays, including
3383 allocatables and pointers.
3385 Note: Currently, GNU Fortran does not support the array descriptor
3386 (dope vector) as specified in the Technical Specification, but uses
3387 an array descriptor with different fields. The Chasm Language
3388 Interoperability Tools, @url{http://chasm-interop.sourceforge.net/},
3389 provide an interface to GNU Fortran's array descriptor.
3391 The Technical Specification adds the following new features, which
3392 are supported by GNU Fortran:
3396 @item The @code{ASYNCHRONOUS} attribute has been clarified and
3397 extended to allow its use with asynchronous communication in
3398 user-provided libraries such as in implementations of the
3399 Message Passing Interface specification.
3401 @item Many constraints have been relaxed, in particular for
3402 the @code{C_LOC} and @code{C_F_POINTER} intrinsics.
3404 @item The @code{OPTIONAL} attribute is now allowed for dummy
3405 arguments; an absent argument matches a @code{NULL} pointer.
3407 @item Assumed types (@code{TYPE(*)}) have been added, which may
3408 only be used for dummy arguments. They are unlimited polymorphic
3409 but contrary to @code{CLASS(*)} they do not contain any type
3410 information, similar to C's @code{void *} pointers. Expressions
3411 of any type and kind can be passed; thus, it can be used as
3412 replacement for @code{TYPE(C_PTR)}, avoiding the use of
3413 @code{C_LOC} in the caller.
3415 Note, however, that @code{TYPE(*)} only accepts scalar arguments,
3416 unless the @code{DIMENSION} is explicitly specified. As
3417 @code{DIMENSION(*)} only supports array (including array elements) but
3418 no scalars, it is not a full replacement for @code{C_LOC}. On the
3419 other hand, assumed-type assumed-rank dummy arguments
3420 (@code{TYPE(*), DIMENSION(..)}) allow for both scalars and arrays, but
3421 require special code on the callee side to handle the array descriptor.
3423 @item Assumed-rank arrays (@code{DIMENSION(..)}) as dummy argument
3424 allow that scalars and arrays of any rank can be passed as actual
3425 argument. As the Technical Specification does not provide for direct
3426 means to operate with them, they have to be used either from the C side
3427 or be converted using @code{C_LOC} and @code{C_F_POINTER} to scalars
3428 or arrays of a specific rank. The rank can be determined using the
3429 @code{RANK} intrinisic.
3433 Currently unimplemented:
3437 @item GNU Fortran always uses an array descriptor, which does not
3438 match the one of the Technical Specification. The
3439 @code{ISO_Fortran_binding.h} header file and the C functions it
3440 specifies are not available.
3442 @item Using assumed-shape, assumed-rank and deferred-shape arrays in
3443 @code{BIND(C)} procedures is not fully supported. In particular,
3444 C interoperable strings of other length than one are not supported
3445 as this requires the new array descriptor.
3449 @node GNU Fortran Compiler Directives
3450 @section GNU Fortran Compiler Directives
3453 * ATTRIBUTES directive::
3454 * UNROLL directive::
3457 @node ATTRIBUTES directive
3458 @subsection ATTRIBUTES directive
3460 The Fortran standard describes how a conforming program shall
3461 behave; however, the exact implementation is not standardized. In order
3462 to allow the user to choose specific implementation details, compiler
3463 directives can be used to set attributes of variables and procedures
3464 which are not part of the standard. Whether a given attribute is
3465 supported and its exact effects depend on both the operating system and
3466 on the processor; see
3467 @ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)}
3470 For procedures and procedure pointers, the following attributes can
3471 be used to change the calling convention:
3474 @item @code{CDECL} -- standard C calling convention
3475 @item @code{STDCALL} -- convention where the called procedure pops the stack
3476 @item @code{FASTCALL} -- part of the arguments are passed via registers
3477 instead using the stack
3480 Besides changing the calling convention, the attributes also influence
3481 the decoration of the symbol name, e.g., by a leading underscore or by
3482 a trailing at-sign followed by the number of bytes on the stack. When
3483 assigning a procedure to a procedure pointer, both should use the same
3486 On some systems, procedures and global variables (module variables and
3487 @code{COMMON} blocks) need special handling to be accessible when they
3488 are in a shared library. The following attributes are available:
3491 @item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL
3492 @item @code{DLLIMPORT} -- reference the function or variable using a
3496 For dummy arguments, the @code{NO_ARG_CHECK} attribute can be used; in
3497 other compilers, it is also known as @code{IGNORE_TKR}. For dummy arguments
3498 with this attribute actual arguments of any type and kind (similar to
3499 @code{TYPE(*)}), scalars and arrays of any rank (no equivalent
3500 in Fortran standard) are accepted. As with @code{TYPE(*)}, the argument
3501 is unlimited polymorphic and no type information is available.
3502 Additionally, the argument may only be passed to dummy arguments
3503 with the @code{NO_ARG_CHECK} attribute and as argument to the
3504 @code{PRESENT} intrinsic function and to @code{C_LOC} of the
3505 @code{ISO_C_BINDING} module.
3507 Variables with @code{NO_ARG_CHECK} attribute shall be of assumed-type
3508 (@code{TYPE(*)}; recommended) or of type @code{INTEGER}, @code{LOGICAL},
3509 @code{REAL} or @code{COMPLEX}. They shall not have the @code{ALLOCATE},
3510 @code{CODIMENSION}, @code{INTENT(OUT)}, @code{POINTER} or @code{VALUE}
3511 attribute; furthermore, they shall be either scalar or of assumed-size
3512 (@code{dimension(*)}). As @code{TYPE(*)}, the @code{NO_ARG_CHECK} attribute
3513 requires an explicit interface.
3516 @item @code{NO_ARG_CHECK} -- disable the type, kind and rank checking
3520 The attributes are specified using the syntax
3522 @code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list}
3524 where in free-form source code only whitespace is allowed before @code{!GCC$}
3525 and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall
3526 start in the first column.
3528 For procedures, the compiler directives shall be placed into the body
3529 of the procedure; for variables and procedure pointers, they shall be in
3530 the same declaration part as the variable or procedure pointer.
3533 @node UNROLL directive
3534 @subsection UNROLL directive
3536 The syntax of the directive is
3538 @code{!GCC$ unroll N}
3540 You can use this directive to control how many times a loop should be unrolled.
3541 It must be placed immediately before a @code{DO} loop and applies only to the
3542 loop that follows. N is an integer constant specifying the unrolling factor.
3543 The values of 0 and 1 block any unrolling of the loop.
3547 @node Non-Fortran Main Program
3548 @section Non-Fortran Main Program
3551 * _gfortran_set_args:: Save command-line arguments
3552 * _gfortran_set_options:: Set library option flags
3553 * _gfortran_set_convert:: Set endian conversion
3554 * _gfortran_set_record_marker:: Set length of record markers
3555 * _gfortran_set_fpe:: Set when a Floating Point Exception should be raised
3556 * _gfortran_set_max_subrecord_length:: Set subrecord length
3559 Even if you are doing mixed-language programming, it is very
3560 likely that you do not need to know or use the information in this
3561 section. Since it is about the internal structure of GNU Fortran,
3562 it may also change in GCC minor releases.
3564 When you compile a @code{PROGRAM} with GNU Fortran, a function
3565 with the name @code{main} (in the symbol table of the object file)
3566 is generated, which initializes the libgfortran library and then
3567 calls the actual program which uses the name @code{MAIN__}, for
3568 historic reasons. If you link GNU Fortran compiled procedures
3569 to, e.g., a C or C++ program or to a Fortran program compiled by
3570 a different compiler, the libgfortran library is not initialized
3571 and thus a few intrinsic procedures do not work properly, e.g.
3572 those for obtaining the command-line arguments.
3574 Therefore, if your @code{PROGRAM} is not compiled with
3575 GNU Fortran and the GNU Fortran compiled procedures require
3576 intrinsics relying on the library initialization, you need to
3577 initialize the library yourself. Using the default options,
3578 gfortran calls @code{_gfortran_set_args} and
3579 @code{_gfortran_set_options}. The initialization of the former
3580 is needed if the called procedures access the command line
3581 (and for backtracing); the latter sets some flags based on the
3582 standard chosen or to enable backtracing. In typical programs,
3583 it is not necessary to call any initialization function.
3585 If your @code{PROGRAM} is compiled with GNU Fortran, you shall
3586 not call any of the following functions. The libgfortran
3587 initialization functions are shown in C syntax but using C
3588 bindings they are also accessible from Fortran.
3591 @node _gfortran_set_args
3592 @subsection @code{_gfortran_set_args} --- Save command-line arguments
3593 @fnindex _gfortran_set_args
3594 @cindex libgfortran initialization, set_args
3597 @item @emph{Description}:
3598 @code{_gfortran_set_args} saves the command-line arguments; this
3599 initialization is required if any of the command-line intrinsics
3600 is called. Additionally, it shall be called if backtracing is
3601 enabled (see @code{_gfortran_set_options}).
3603 @item @emph{Syntax}:
3604 @code{void _gfortran_set_args (int argc, char *argv[])}
3606 @item @emph{Arguments}:
3607 @multitable @columnfractions .15 .70
3608 @item @var{argc} @tab number of command line argument strings
3609 @item @var{argv} @tab the command-line argument strings; argv[0]
3610 is the pathname of the executable itself.
3613 @item @emph{Example}:
3615 int main (int argc, char *argv[])
3617 /* Initialize libgfortran. */
3618 _gfortran_set_args (argc, argv);
3625 @node _gfortran_set_options
3626 @subsection @code{_gfortran_set_options} --- Set library option flags
3627 @fnindex _gfortran_set_options
3628 @cindex libgfortran initialization, set_options
3631 @item @emph{Description}:
3632 @code{_gfortran_set_options} sets several flags related to the Fortran
3633 standard to be used, whether backtracing should be enabled
3634 and whether range checks should be performed. The syntax allows for
3635 upward compatibility since the number of passed flags is specified; for
3636 non-passed flags, the default value is used. See also
3637 @pxref{Code Gen Options}. Please note that not all flags are actually
3640 @item @emph{Syntax}:
3641 @code{void _gfortran_set_options (int num, int options[])}
3643 @item @emph{Arguments}:
3644 @multitable @columnfractions .15 .70
3645 @item @var{num} @tab number of options passed
3646 @item @var{argv} @tab The list of flag values
3649 @item @emph{option flag list}:
3650 @multitable @columnfractions .15 .70
3651 @item @var{option}[0] @tab Allowed standard; can give run-time errors
3652 if e.g. an input-output edit descriptor is invalid in a given
3653 standard. Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1),
3654 @code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4),
3655 @code{GFC_STD_F95} (8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU}
3656 (32), @code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128),
3657 @code{GFC_STD_F2008_OBS} (256), @code{GFC_STD_F2008_TS} (512),
3658 @code{GFC_STD_F2018} (1024), @code{GFC_STD_F2018_OBS} (2048), and
3659 @code{GFC_STD=F2018_DEL} (4096). Default: @code{GFC_STD_F95_OBS |
3660 GFC_STD_F95_DEL | GFC_STD_F95 | GFC_STD_F2003 | GFC_STD_F2008 |
3661 GFC_STD_F2008_TS | GFC_STD_F2008_OBS | GFC_STD_F77 | GFC_STD_F2018 |
3662 GFC_STD_F2018_OBS | GFC_STD_F2018_DEL | GFC_STD_GNU | GFC_STD_LEGACY}.
3663 @item @var{option}[1] @tab Standard-warning flag; prints a warning to
3664 standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}.
3665 @item @var{option}[2] @tab If non zero, enable pedantic checking.
3667 @item @var{option}[3] @tab Unused.
3668 @item @var{option}[4] @tab If non zero, enable backtracing on run-time
3669 errors. Default: off. (Default in the compiler: on.)
3670 Note: Installs a signal handler and requires command-line
3671 initialization using @code{_gfortran_set_args}.
3672 @item @var{option}[5] @tab If non zero, supports signed zeros.
3674 @item @var{option}[6] @tab Enables run-time checking. Possible values
3675 are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2),
3676 GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (16), GFC_RTCHECK_POINTER (32).
3678 @item @var{option}[7] @tab Unused.
3679 @item @var{option}[8] @tab Show a warning when invoking @code{STOP} and
3680 @code{ERROR STOP} if a floating-point exception occurred. Possible values
3681 are (bitwise or-ed) @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3682 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3683 @code{GFC_FPE_UNDERFLOW} (16), @code{GFC_FPE_INEXACT} (32). Default: None (0).
3684 (Default in the compiler: @code{GFC_FPE_INVALID | GFC_FPE_DENORMAL |
3685 GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW}.)
3688 @item @emph{Example}:
3690 /* Use gfortran 4.9 default options. */
3691 static int options[] = @{68, 511, 0, 0, 1, 1, 0, 0, 31@};
3692 _gfortran_set_options (9, &options);
3697 @node _gfortran_set_convert
3698 @subsection @code{_gfortran_set_convert} --- Set endian conversion
3699 @fnindex _gfortran_set_convert
3700 @cindex libgfortran initialization, set_convert
3703 @item @emph{Description}:
3704 @code{_gfortran_set_convert} set the representation of data for
3707 @item @emph{Syntax}:
3708 @code{void _gfortran_set_convert (int conv)}
3710 @item @emph{Arguments}:
3711 @multitable @columnfractions .15 .70
3712 @item @var{conv} @tab Endian conversion, possible values:
3713 GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1),
3714 GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3).
3717 @item @emph{Example}:
3719 int main (int argc, char *argv[])
3721 /* Initialize libgfortran. */
3722 _gfortran_set_args (argc, argv);
3723 _gfortran_set_convert (1);
3730 @node _gfortran_set_record_marker
3731 @subsection @code{_gfortran_set_record_marker} --- Set length of record markers
3732 @fnindex _gfortran_set_record_marker
3733 @cindex libgfortran initialization, set_record_marker
3736 @item @emph{Description}:
3737 @code{_gfortran_set_record_marker} sets the length of record markers
3738 for unformatted files.
3740 @item @emph{Syntax}:
3741 @code{void _gfortran_set_record_marker (int val)}
3743 @item @emph{Arguments}:
3744 @multitable @columnfractions .15 .70
3745 @item @var{val} @tab Length of the record marker; valid values
3746 are 4 and 8. Default is 4.
3749 @item @emph{Example}:
3751 int main (int argc, char *argv[])
3753 /* Initialize libgfortran. */
3754 _gfortran_set_args (argc, argv);
3755 _gfortran_set_record_marker (8);
3762 @node _gfortran_set_fpe
3763 @subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps
3764 @fnindex _gfortran_set_fpe
3765 @cindex libgfortran initialization, set_fpe
3768 @item @emph{Description}:
3769 @code{_gfortran_set_fpe} enables floating point exception traps for
3770 the specified exceptions. On most systems, this will result in a
3771 SIGFPE signal being sent and the program being aborted.
3773 @item @emph{Syntax}:
3774 @code{void _gfortran_set_fpe (int val)}
3776 @item @emph{Arguments}:
3777 @multitable @columnfractions .15 .70
3778 @item @var{option}[0] @tab IEEE exceptions. Possible values are
3779 (bitwise or-ed) zero (0, default) no trapping,
3780 @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3781 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3782 @code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32).
3785 @item @emph{Example}:
3787 int main (int argc, char *argv[])
3789 /* Initialize libgfortran. */
3790 _gfortran_set_args (argc, argv);
3791 /* FPE for invalid operations such as SQRT(-1.0). */
3792 _gfortran_set_fpe (1);
3799 @node _gfortran_set_max_subrecord_length
3800 @subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length
3801 @fnindex _gfortran_set_max_subrecord_length
3802 @cindex libgfortran initialization, set_max_subrecord_length
3805 @item @emph{Description}:
3806 @code{_gfortran_set_max_subrecord_length} set the maximum length
3807 for a subrecord. This option only makes sense for testing and
3808 debugging of unformatted I/O.
3810 @item @emph{Syntax}:
3811 @code{void _gfortran_set_max_subrecord_length (int val)}
3813 @item @emph{Arguments}:
3814 @multitable @columnfractions .15 .70
3815 @item @var{val} @tab the maximum length for a subrecord;
3816 the maximum permitted value is 2147483639, which is also
3820 @item @emph{Example}:
3822 int main (int argc, char *argv[])
3824 /* Initialize libgfortran. */
3825 _gfortran_set_args (argc, argv);
3826 _gfortran_set_max_subrecord_length (8);
3833 @node Naming and argument-passing conventions
3834 @section Naming and argument-passing conventions
3836 This section gives an overview about the naming convention of procedures
3837 and global variables and about the argument passing conventions used by
3838 GNU Fortran. If a C binding has been specified, the naming convention
3839 and some of the argument-passing conventions change. If possible,
3840 mixed-language and mixed-compiler projects should use the better defined
3841 C binding for interoperability. See @pxref{Interoperability with C}.
3844 * Naming conventions::
3845 * Argument passing conventions::
3849 @node Naming conventions
3850 @subsection Naming conventions
3852 According the Fortran standard, valid Fortran names consist of a letter
3853 between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0},
3854 @code{1} to @code{9} and underscores (@code{_}) with the restriction
3855 that names may only start with a letter. As vendor extension, the
3856 dollar sign (@code{$}) is additionally permitted with the option
3857 @option{-fdollar-ok}, but not as first character and only if the
3858 target system supports it.
3860 By default, the procedure name is the lower-cased Fortran name with an
3861 appended underscore (@code{_}); using @option{-fno-underscoring} no
3862 underscore is appended while @code{-fsecond-underscore} appends two
3863 underscores. Depending on the target system and the calling convention,
3864 the procedure might be additionally dressed; for instance, on 32bit
3865 Windows with @code{stdcall}, an at-sign @code{@@} followed by an integer
3866 number is appended. For the changing the calling convention, see
3867 @pxref{GNU Fortran Compiler Directives}.
3869 For common blocks, the same convention is used, i.e. by default an
3870 underscore is appended to the lower-cased Fortran name. Blank commons
3871 have the name @code{__BLNK__}.
3873 For procedures and variables declared in the specification space of a
3874 module, the name is formed by @code{__}, followed by the lower-cased
3875 module name, @code{_MOD_}, and the lower-cased Fortran name. Note that
3876 no underscore is appended.
3879 @node Argument passing conventions
3880 @subsection Argument passing conventions
3882 Subroutines do not return a value (matching C99's @code{void}) while
3883 functions either return a value as specified in the platform ABI or
3884 the result variable is passed as hidden argument to the function and
3885 no result is returned. A hidden result variable is used when the
3886 result variable is an array or of type @code{CHARACTER}.
3888 Arguments are passed according to the platform ABI. In particular,
3889 complex arguments might not be compatible to a struct with two real
3890 components for the real and imaginary part. The argument passing
3891 matches the one of C99's @code{_Complex}. Functions with scalar
3892 complex result variables return their value and do not use a
3893 by-reference argument. Note that with the @option{-ff2c} option,
3894 the argument passing is modified and no longer completely matches
3895 the platform ABI. Some other Fortran compilers use @code{f2c}
3896 semantic by default; this might cause problems with
3899 GNU Fortran passes most arguments by reference, i.e. by passing a
3900 pointer to the data. Note that the compiler might use a temporary
3901 variable into which the actual argument has been copied, if required
3902 semantically (copy-in/copy-out).
3904 For arguments with @code{ALLOCATABLE} and @code{POINTER}
3905 attribute (including procedure pointers), a pointer to the pointer
3906 is passed such that the pointer address can be modified in the
3909 For dummy arguments with the @code{VALUE} attribute: Scalar arguments
3910 of the type @code{INTEGER}, @code{LOGICAL}, @code{REAL} and
3911 @code{COMPLEX} are passed by value according to the platform ABI.
3912 (As vendor extension and not recommended, using @code{%VAL()} in the
3913 call to a procedure has the same effect.) For @code{TYPE(C_PTR)} and
3914 procedure pointers, the pointer itself is passed such that it can be
3915 modified without affecting the caller.
3916 @c FIXME: Document how VALUE is handled for CHARACTER, TYPE,
3917 @c CLASS and arrays, i.e. whether the copy-in is done in the caller
3918 @c or in the callee.
3920 For Boolean (@code{LOGICAL}) arguments, please note that GCC expects
3921 only the integer value 0 and 1. If a GNU Fortran @code{LOGICAL}
3922 variable contains another integer value, the result is undefined.
3923 As some other Fortran compilers use @math{-1} for @code{.TRUE.},
3924 extra care has to be taken -- such as passing the value as
3925 @code{INTEGER}. (The same value restriction also applies to other
3926 front ends of GCC, e.g. to GCC's C99 compiler for @code{_Bool}
3927 or GCC's Ada compiler for @code{Boolean}.)
3929 For arguments of @code{CHARACTER} type, the character length is passed
3930 as a hidden argument at the end of the argument list. For
3931 deferred-length strings, the value is passed by reference, otherwise
3932 by value. The character length has the C type @code{size_t} (or
3933 @code{INTEGER(kind=C_SIZE_T)} in Fortran). Note that this is
3934 different to older versions of the GNU Fortran compiler, where the
3935 type of the hidden character length argument was a C @code{int}. In
3936 order to retain compatibility with older versions, one can e.g. for
3937 the following Fortran procedure
3940 subroutine fstrlen (s, a)
3941 character(len=*) :: s
3944 end subroutine fstrlen
3947 define the corresponding C prototype as follows:
3951 typedef size_t fortran_charlen_t;
3953 typedef int fortran_charlen_t;
3956 void fstrlen_ (char*, int*, fortran_charlen_t);
3959 In order to avoid such compiler-specific details, for new code it is
3960 instead recommended to use the ISO_C_BINDING feature.
3962 Note with C binding, @code{CHARACTER(len=1)} result variables are
3963 returned according to the platform ABI and no hidden length argument
3964 is used for dummy arguments; with @code{VALUE}, those variables are
3967 For @code{OPTIONAL} dummy arguments, an absent argument is denoted
3968 by a NULL pointer, except for scalar dummy arguments of type
3969 @code{INTEGER}, @code{LOGICAL}, @code{REAL} and @code{COMPLEX}
3970 which have the @code{VALUE} attribute. For those, a hidden Boolean
3971 argument (@code{logical(kind=C_bool),value}) is used to indicate
3972 whether the argument is present.
3974 Arguments which are assumed-shape, assumed-rank or deferred-rank
3975 arrays or, with @option{-fcoarray=lib}, allocatable scalar coarrays use
3976 an array descriptor. All other arrays pass the address of the
3977 first element of the array. With @option{-fcoarray=lib}, the token
3978 and the offset belonging to nonallocatable coarrays dummy arguments
3979 are passed as hidden argument along the character length hidden
3980 arguments. The token is an oparque pointer identifying the coarray
3981 and the offset is a passed-by-value integer of kind @code{C_PTRDIFF_T},
3982 denoting the byte offset between the base address of the coarray and
3983 the passed scalar or first element of the passed array.
3985 The arguments are passed in the following order
3987 @item Result variable, when the function result is passed by reference
3988 @item Character length of the function result, if it is a of type
3989 @code{CHARACTER} and no C binding is used
3990 @item The arguments in the order in which they appear in the Fortran
3992 @item The the present status for optional arguments with value attribute,
3993 which are internally passed by value
3994 @item The character length and/or coarray token and offset for the first
3995 argument which is a @code{CHARACTER} or a nonallocatable coarray dummy
3996 argument, followed by the hidden arguments of the next dummy argument
4001 @c ---------------------------------------------------------------------
4002 @c Coarray Programming
4003 @c ---------------------------------------------------------------------
4005 @node Coarray Programming
4006 @chapter Coarray Programming
4010 * Type and enum ABI Documentation::
4011 * Function ABI Documentation::
4015 @node Type and enum ABI Documentation
4016 @section Type and enum ABI Documentation
4021 * caf_deregister_t::
4027 @subsection @code{caf_token_t}
4029 Typedef of type @code{void *} on the compiler side. Can be any data
4030 type on the library side.
4032 @node caf_register_t
4033 @subsection @code{caf_register_t}
4035 Indicates which kind of coarray variable should be registered.
4038 typedef enum caf_register_t {
4039 CAF_REGTYPE_COARRAY_STATIC,
4040 CAF_REGTYPE_COARRAY_ALLOC,
4041 CAF_REGTYPE_LOCK_STATIC,
4042 CAF_REGTYPE_LOCK_ALLOC,
4043 CAF_REGTYPE_CRITICAL,
4044 CAF_REGTYPE_EVENT_STATIC,
4045 CAF_REGTYPE_EVENT_ALLOC,
4046 CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY,
4047 CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY
4052 The values @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and
4053 @code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} are for allocatable components
4054 in derived type coarrays only. The first one sets up the token without
4055 allocating memory for allocatable component. The latter one only allocates the
4056 memory for an allocatable component in a derived type coarray. The token
4057 needs to be setup previously by the REGISTER_ONLY. This allows to have
4058 allocatable components un-allocated on some images. The status whether an
4059 allocatable component is allocated on a remote image can be queried by
4060 @code{_caf_is_present} which used internally by the @code{ALLOCATED}
4063 @node caf_deregister_t
4064 @subsection @code{caf_deregister_t}
4067 typedef enum caf_deregister_t {
4068 CAF_DEREGTYPE_COARRAY_DEREGISTER,
4069 CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY
4074 Allows to specifiy the type of deregistration of a coarray object. The
4075 @code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} flag is only allowed for
4076 allocatable components in derived type coarrays.
4078 @node caf_reference_t
4079 @subsection @code{caf_reference_t}
4081 The structure used for implementing arbitrary reference chains.
4082 A @code{CAF_REFERENCE_T} allows to specify a component reference or any kind
4083 of array reference of any rank supported by gfortran. For array references all
4084 kinds as known by the compiler/Fortran standard are supported indicated by
4088 typedef enum caf_ref_type_t {
4089 /* Reference a component of a derived type, either regular one or an
4090 allocatable or pointer type. For regular ones idx in caf_reference_t is
4093 /* Reference an allocatable array. */
4095 /* Reference a non-allocatable/non-pointer array. I.e., the coarray object
4096 has no array descriptor associated and the addressing is done
4097 completely using the ref. */
4098 CAF_REF_STATIC_ARRAY
4103 typedef enum caf_array_ref_t {
4104 /* No array ref. This terminates the array ref. */
4105 CAF_ARR_REF_NONE = 0,
4106 /* Reference array elements given by a vector. Only for this mode
4107 caf_reference_t.u.a.dim[i].v is valid. */
4109 /* A full array ref (:). */
4111 /* Reference a range on elements given by start, end and stride. */
4113 /* Only a single item is referenced given in the start member. */
4115 /* An array ref of the kind (i:), where i is an arbitrary valid index in the
4116 array. The index i is given in the start member. */
4117 CAF_ARR_REF_OPEN_END,
4118 /* An array ref of the kind (:i), where the lower bound of the array ref
4119 is given by the remote side. The index i is given in the end member. */
4120 CAF_ARR_REF_OPEN_START
4125 /* References to remote components of a derived type. */
4126 typedef struct caf_reference_t {
4127 /* A pointer to the next ref or NULL. */
4128 struct caf_reference_t *next;
4129 /* The type of the reference. */
4130 /* caf_ref_type_t, replaced by int to allow specification in fortran FE. */
4132 /* The size of an item referenced in bytes. I.e. in an array ref this is
4133 the factor to advance the array pointer with to get to the next item.
4134 For component refs this gives just the size of the element referenced. */
4138 /* The offset (in bytes) of the component in the derived type.
4139 Unused for allocatable or pointer components. */
4141 /* The offset (in bytes) to the caf_token associated with this
4142 component. NULL, when not allocatable/pointer ref. */
4143 ptrdiff_t caf_token_offset;
4146 /* The mode of the array ref. See CAF_ARR_REF_*. */
4147 /* caf_array_ref_t, replaced by unsigend char to allow specification in
4149 unsigned char mode[GFC_MAX_DIMENSIONS];
4150 /* The type of a static array. Unset for array's with descriptors. */
4151 int static_array_type;
4152 /* Subscript refs (s) or vector refs (v). */
4155 /* The start and end boundary of the ref and the stride. */
4156 index_type start, end, stride;
4159 /* nvec entries of kind giving the elements to reference. */
4161 /* The number of entries in vector. */
4163 /* The integer kind used for the elements in vector. */
4166 } dim[GFC_MAX_DIMENSIONS];
4172 The references make up a single linked list of reference operations. The
4173 @code{NEXT} member links to the next reference or NULL to indicate the end of
4174 the chain. Component and array refs can be arbitrarly mixed as long as they
4175 comply to the Fortran standard.
4178 The member @code{STATIC_ARRAY_TYPE} is used only when the @code{TYPE} is
4179 @code{CAF_REF_STATIC_ARRAY}. The member gives the type of the data referenced.
4180 Because no array descriptor is available for a descriptor-less array and
4181 type conversion still needs to take place the type is transported here.
4183 At the moment @code{CAF_ARR_REF_VECTOR} is not implemented in the front end for
4184 descriptor-less arrays. The library caf_single has untested support for it.
4187 @subsection @code{caf_team_t}
4189 Opaque pointer to represent a team-handle. This type is a stand-in for the
4190 future implementation of teams. It is about to change without further notice.
4192 @node Function ABI Documentation
4193 @section Function ABI Documentation
4196 * _gfortran_caf_init:: Initialiation function
4197 * _gfortran_caf_finish:: Finalization function
4198 * _gfortran_caf_this_image:: Querying the image number
4199 * _gfortran_caf_num_images:: Querying the maximal number of images
4200 * _gfortran_caf_image_status :: Query the status of an image
4201 * _gfortran_caf_failed_images :: Get an array of the indexes of the failed images
4202 * _gfortran_caf_stopped_images :: Get an array of the indexes of the stopped images
4203 * _gfortran_caf_register:: Registering coarrays
4204 * _gfortran_caf_deregister:: Deregistering coarrays
4205 * _gfortran_caf_is_present:: Query whether an allocatable or pointer component in a derived type coarray is allocated
4206 * _gfortran_caf_send:: Sending data from a local image to a remote image
4207 * _gfortran_caf_get:: Getting data from a remote image
4208 * _gfortran_caf_sendget:: Sending data between remote images
4209 * _gfortran_caf_send_by_ref:: Sending data from a local image to a remote image using enhanced references
4210 * _gfortran_caf_get_by_ref:: Getting data from a remote image using enhanced references
4211 * _gfortran_caf_sendget_by_ref:: Sending data between remote images using enhanced references
4212 * _gfortran_caf_lock:: Locking a lock variable
4213 * _gfortran_caf_unlock:: Unlocking a lock variable
4214 * _gfortran_caf_event_post:: Post an event
4215 * _gfortran_caf_event_wait:: Wait that an event occurred
4216 * _gfortran_caf_event_query:: Query event count
4217 * _gfortran_caf_sync_all:: All-image barrier
4218 * _gfortran_caf_sync_images:: Barrier for selected images
4219 * _gfortran_caf_sync_memory:: Wait for completion of segment-memory operations
4220 * _gfortran_caf_error_stop:: Error termination with exit code
4221 * _gfortran_caf_error_stop_str:: Error termination with string
4222 * _gfortran_caf_fail_image :: Mark the image failed and end its execution
4223 * _gfortran_caf_atomic_define:: Atomic variable assignment
4224 * _gfortran_caf_atomic_ref:: Atomic variable reference
4225 * _gfortran_caf_atomic_cas:: Atomic compare and swap
4226 * _gfortran_caf_atomic_op:: Atomic operation
4227 * _gfortran_caf_co_broadcast:: Sending data to all images
4228 * _gfortran_caf_co_max:: Collective maximum reduction
4229 * _gfortran_caf_co_min:: Collective minimum reduction
4230 * _gfortran_caf_co_sum:: Collective summing reduction
4231 * _gfortran_caf_co_reduce:: Generic collective reduction
4235 @node _gfortran_caf_init
4236 @subsection @code{_gfortran_caf_init} --- Initialiation function
4237 @cindex Coarray, _gfortran_caf_init
4240 @item @emph{Description}:
4241 This function is called at startup of the program before the Fortran main
4242 program, if the latter has been compiled with @option{-fcoarray=lib}.
4243 It takes as arguments the command-line arguments of the program. It is
4244 permitted to pass two @code{NULL} pointers as argument; if non-@code{NULL},
4245 the library is permitted to modify the arguments.
4247 @item @emph{Syntax}:
4248 @code{void _gfortran_caf_init (int *argc, char ***argv)}
4250 @item @emph{Arguments}:
4251 @multitable @columnfractions .15 .70
4252 @item @var{argc} @tab intent(inout) An integer pointer with the number of
4253 arguments passed to the program or @code{NULL}.
4254 @item @var{argv} @tab intent(inout) A pointer to an array of strings with the
4255 command-line arguments or @code{NULL}.
4259 The function is modelled after the initialization function of the Message
4260 Passing Interface (MPI) specification. Due to the way coarray registration
4261 works, it might not be the first call to the library. If the main program is
4262 not written in Fortran and only a library uses coarrays, it can happen that
4263 this function is never called. Therefore, it is recommended that the library
4264 does not rely on the passed arguments and whether the call has been done.
4268 @node _gfortran_caf_finish
4269 @subsection @code{_gfortran_caf_finish} --- Finalization function
4270 @cindex Coarray, _gfortran_caf_finish
4273 @item @emph{Description}:
4274 This function is called at the end of the Fortran main program, if it has
4275 been compiled with the @option{-fcoarray=lib} option.
4277 @item @emph{Syntax}:
4278 @code{void _gfortran_caf_finish (void)}
4281 For non-Fortran programs, it is recommended to call the function at the end
4282 of the main program. To ensure that the shutdown is also performed for
4283 programs where this function is not explicitly invoked, for instance
4284 non-Fortran programs or calls to the system's exit() function, the library
4285 can use a destructor function. Note that programs can also be terminated
4286 using the STOP and ERROR STOP statements; those use different library calls.
4290 @node _gfortran_caf_this_image
4291 @subsection @code{_gfortran_caf_this_image} --- Querying the image number
4292 @cindex Coarray, _gfortran_caf_this_image
4295 @item @emph{Description}:
4296 This function returns the current image number, which is a positive number.
4298 @item @emph{Syntax}:
4299 @code{int _gfortran_caf_this_image (int distance)}
4301 @item @emph{Arguments}:
4302 @multitable @columnfractions .15 .70
4303 @item @var{distance} @tab As specified for the @code{this_image} intrinsic
4304 in TS18508. Shall be a non-negative number.
4308 If the Fortran intrinsic @code{this_image} is invoked without an argument, which
4309 is the only permitted form in Fortran 2008, GCC passes @code{0} as
4314 @node _gfortran_caf_num_images
4315 @subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images
4316 @cindex Coarray, _gfortran_caf_num_images
4319 @item @emph{Description}:
4320 This function returns the number of images in the current team, if
4321 @var{distance} is 0 or the number of images in the parent team at the specified
4322 distance. If failed is -1, the function returns the number of all images at
4323 the specified distance; if it is 0, the function returns the number of
4324 nonfailed images, and if it is 1, it returns the number of failed images.
4326 @item @emph{Syntax}:
4327 @code{int _gfortran_caf_num_images(int distance, int failed)}
4329 @item @emph{Arguments}:
4330 @multitable @columnfractions .15 .70
4331 @item @var{distance} @tab the distance from this image to the ancestor.
4333 @item @var{failed} @tab shall be -1, 0, or 1
4337 This function follows TS18508. If the num_image intrinsic has no arguments,
4338 then the compiler passes @code{distance=0} and @code{failed=-1} to the function.
4342 @node _gfortran_caf_image_status
4343 @subsection @code{_gfortran_caf_image_status} --- Query the status of an image
4344 @cindex Coarray, _gfortran_caf_image_status
4347 @item @emph{Description}:
4348 Get the status of the image given by the id @var{image} of the team given by
4349 @var{team}. Valid results are zero, for image is ok, @code{STAT_STOPPED_IMAGE}
4350 from the ISO_FORTRAN_ENV module to indicate that the image has been stopped and
4351 @code{STAT_FAILED_IMAGE} also from ISO_FORTRAN_ENV to indicate that the image
4352 has executed a @code{FAIL IMAGE} statement.
4354 @item @emph{Syntax}:
4355 @code{int _gfortran_caf_image_status (int image, caf_team_t * team)}
4357 @item @emph{Arguments}:
4358 @multitable @columnfractions .15 .70
4359 @item @var{image} @tab the positive scalar id of the image in the current TEAM.
4360 @item @var{team} @tab optional; team on the which the inquiry is to be
4365 This function follows TS18508. Because team-functionality is not yet
4366 implemented a null-pointer is passed for the @var{team} argument at the moment.
4370 @node _gfortran_caf_failed_images
4371 @subsection @code{_gfortran_caf_failed_images} --- Get an array of the indexes of the failed images
4372 @cindex Coarray, _gfortran_caf_failed_images
4375 @item @emph{Description}:
4376 Get an array of image indexes in the current @var{team} that have failed. The
4377 array is sorted ascendingly. When @var{team} is not provided the current team
4378 is to be used. When @var{kind} is provided then the resulting array is of that
4379 integer kind else it is of default integer kind. The returns an unallocated
4380 size zero array when no images have failed.
4382 @item @emph{Syntax}:
4383 @code{int _gfortran_caf_failed_images (caf_team_t * team, int * kind)}
4385 @item @emph{Arguments}:
4386 @multitable @columnfractions .15 .70
4387 @item @var{team} @tab optional; team on the which the inquiry is to be
4389 @item @var{image} @tab optional; the kind of the resulting integer array.
4393 This function follows TS18508. Because team-functionality is not yet
4394 implemented a null-pointer is passed for the @var{team} argument at the moment.
4398 @node _gfortran_caf_stopped_images
4399 @subsection @code{_gfortran_caf_stopped_images} --- Get an array of the indexes of the stopped images
4400 @cindex Coarray, _gfortran_caf_stopped_images
4403 @item @emph{Description}:
4404 Get an array of image indexes in the current @var{team} that have stopped. The
4405 array is sorted ascendingly. When @var{team} is not provided the current team
4406 is to be used. When @var{kind} is provided then the resulting array is of that
4407 integer kind else it is of default integer kind. The returns an unallocated
4408 size zero array when no images have failed.
4410 @item @emph{Syntax}:
4411 @code{int _gfortran_caf_stopped_images (caf_team_t * team, int * kind)}
4413 @item @emph{Arguments}:
4414 @multitable @columnfractions .15 .70
4415 @item @var{team} @tab optional; team on the which the inquiry is to be
4417 @item @var{image} @tab optional; the kind of the resulting integer array.
4421 This function follows TS18508. Because team-functionality is not yet
4422 implemented a null-pointer is passed for the @var{team} argument at the moment.
4426 @node _gfortran_caf_register
4427 @subsection @code{_gfortran_caf_register} --- Registering coarrays
4428 @cindex Coarray, _gfortran_caf_register
4431 @item @emph{Description}:
4432 Registers memory for a coarray and creates a token to identify the coarray. The
4433 routine is called for both coarrays with @code{SAVE} attribute and using an
4434 explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a
4435 @code{NULL} pointer, the function shall abort with printing an error message
4436 and starting the error termination. If no error occurs and @var{STAT} is
4437 present, it shall be set to zero. Otherwise, it shall be set to a positive
4438 value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing
4439 the failure. The routine shall register the memory provided in the
4440 @code{DATA}-component of the array descriptor @var{DESC}, when that component
4441 is non-@code{NULL}, else it shall allocate sufficient memory and provide a
4442 pointer to it in the @code{DATA}-component of @var{DESC}. The array descriptor
4443 has rank zero, when a scalar object is to be registered and the array
4444 descriptor may be invalid after the call to @code{_gfortran_caf_register}.
4445 When an array is to be allocated the descriptor persists.
4447 For @code{CAF_REGTYPE_COARRAY_STATIC} and @code{CAF_REGTYPE_COARRAY_ALLOC},
4448 the passed size is the byte size requested. For @code{CAF_REGTYPE_LOCK_STATIC},
4449 @code{CAF_REGTYPE_LOCK_ALLOC} and @code{CAF_REGTYPE_CRITICAL} it is the array
4450 size or one for a scalar.
4452 When @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} is used, then only a token
4453 for an allocatable or pointer component is created. The @code{SIZE} parameter
4454 is not used then. On the contrary when
4455 @code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} is specified, then the
4456 @var{token} needs to be registered by a previous call with regtype
4457 @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and either the memory specified
4458 in the @var{DESC}'s data-ptr is registered or allocate when the data-ptr is
4461 @item @emph{Syntax}:
4462 @code{void caf_register (size_t size, caf_register_t type, caf_token_t *token,
4463 gfc_descriptor_t *desc, int *stat, char *errmsg, size_t errmsg_len)}
4465 @item @emph{Arguments}:
4466 @multitable @columnfractions .15 .70
4467 @item @var{size} @tab For normal coarrays, the byte size of the coarray to be
4468 allocated; for lock types and event types, the number of elements.
4469 @item @var{type} @tab one of the caf_register_t types.
4470 @item @var{token} @tab intent(out) An opaque pointer identifying the coarray.
4471 @item @var{desc} @tab intent(inout) The (pseudo) array descriptor.
4472 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
4474 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4475 an error message; may be @code{NULL}
4476 @item @var{errmsg_len} @tab the buffer size of errmsg.
4480 Nonallocatable coarrays have to be registered prior use from remote images.
4481 In order to guarantee this, they have to be registered before the main
4482 program. This can be achieved by creating constructor functions. That is what
4483 GCC does such that also for nonallocatable coarrays the memory is allocated and
4484 no static memory is used. The token permits to identify the coarray; to the
4485 processor, the token is a nonaliasing pointer. The library can, for instance,
4486 store the base address of the coarray in the token, some handle or a more
4487 complicated struct. The library may also store the array descriptor
4488 @var{DESC} when its rank is non-zero.
4490 For lock types, the value shall only be used for checking the allocation
4491 status. Note that for critical blocks, the locking is only required on one
4492 image; in the locking statement, the processor shall always pass an
4493 image index of one for critical-block lock variables
4494 (@code{CAF_REGTYPE_CRITICAL}). For lock types and critical-block variables,
4495 the initial value shall be unlocked (or, respecitively, not in critical
4496 section) such as the value false; for event types, the initial state should
4497 be no event, e.g. zero.
4501 @node _gfortran_caf_deregister
4502 @subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays
4503 @cindex Coarray, _gfortran_caf_deregister
4506 @item @emph{Description}:
4507 Called to free or deregister the memory of a coarray; the processor calls this
4508 function for automatic and explicit deallocation. In case of an error, this
4509 function shall fail with an error message, unless the @var{STAT} variable is
4510 not null. The library is only expected to free memory it allocated itself
4511 during a call to @code{_gfortran_caf_register}.
4513 @item @emph{Syntax}:
4514 @code{void caf_deregister (caf_token_t *token, caf_deregister_t type,
4515 int *stat, char *errmsg, size_t errmsg_len)}
4517 @item @emph{Arguments}:
4518 @multitable @columnfractions .15 .70
4519 @item @var{token} @tab the token to free.
4520 @item @var{type} @tab the type of action to take for the coarray. A
4521 @code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} is allowed only for allocatable or
4522 pointer components of derived type coarrays. The action only deallocates the
4523 local memory without deleting the token.
4524 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
4525 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set
4526 to an error message; may be NULL
4527 @item @var{errmsg_len} @tab the buffer size of errmsg.
4531 For nonalloatable coarrays this function is never called. If a cleanup is
4532 required, it has to be handled via the finish, stop and error stop functions,
4533 and via destructors.
4537 @node _gfortran_caf_is_present
4538 @subsection @code{_gfortran_caf_is_present} --- Query whether an allocatable or pointer component in a derived type coarray is allocated
4539 @cindex Coarray, _gfortran_caf_is_present
4542 @item @emph{Description}:
4543 Used to query the coarray library whether an allocatable component in a derived
4544 type coarray is allocated on a remote image.
4546 @item @emph{Syntax}:
4547 @code{void _gfortran_caf_is_present (caf_token_t token, int image_index,
4548 gfc_reference_t *ref)}
4550 @item @emph{Arguments}:
4551 @multitable @columnfractions .15 .70
4552 @item @var{token} @tab An opaque pointer identifying the coarray.
4553 @item @var{image_index} @tab The ID of the remote image; must be a positive
4555 @item @var{ref} @tab A chain of references to address the allocatable or
4556 pointer component in the derived type coarray. The object reference needs to be
4557 a scalar or a full array reference, respectively.
4562 @node _gfortran_caf_send
4563 @subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image
4564 @cindex Coarray, _gfortran_caf_send
4567 @item @emph{Description}:
4568 Called to send a scalar, an array section or a whole array from a local
4569 to a remote image identified by the image_index.
4571 @item @emph{Syntax}:
4572 @code{void _gfortran_caf_send (caf_token_t token, size_t offset,
4573 int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
4574 gfc_descriptor_t *src, int dst_kind, int src_kind, bool may_require_tmp,
4577 @item @emph{Arguments}:
4578 @multitable @columnfractions .15 .70
4579 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4580 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
4581 shifted compared to the base address of the coarray.
4582 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4584 @item @var{dest} @tab intent(in) Array descriptor for the remote image for the
4585 bounds and the size. The @code{base_addr} shall not be accessed.
4586 @item @var{dst_vector} @tab intent(in) If not NULL, it contains the vector
4587 subscript of the destination array; the values are relative to the dimension
4588 triplet of the dest argument.
4589 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4590 transferred to the remote image
4591 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4592 @item @var{src_kind} @tab intent(in) Kind of the source argument
4593 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4594 it is known at compile time that the @var{dest} and @var{src} either cannot
4595 overlap or overlap (fully or partially) such that walking @var{src} and
4596 @var{dest} in element wise element order (honoring the stride value) will not
4597 lead to wrong results. Otherwise, the value is @code{true}.
4598 @item @var{stat} @tab intent(out) when non-NULL give the result of the
4599 operation, i.e., zero on success and non-zero on error. When NULL and an error
4600 occurs, then an error message is printed and the program is terminated.
4604 It is permitted to have @var{image_index} equal the current image; the memory
4605 of the send-to and the send-from might (partially) overlap in that case. The
4606 implementation has to take care that it handles this case, e.g. using
4607 @code{memmove} which handles (partially) overlapping memory. If
4608 @var{may_require_tmp} is true, the library might additionally create a
4609 temporary variable, unless additional checks show that this is not required
4610 (e.g. because walking backward is possible or because both arrays are
4611 contiguous and @code{memmove} takes care of overlap issues).
4613 Note that the assignment of a scalar to an array is permitted. In addition,
4614 the library has to handle numeric-type conversion and for strings, padding
4615 and different character kinds.
4619 @node _gfortran_caf_get
4620 @subsection @code{_gfortran_caf_get} --- Getting data from a remote image
4621 @cindex Coarray, _gfortran_caf_get
4624 @item @emph{Description}:
4625 Called to get an array section or a whole array from a remote,
4626 image identified by the image_index.
4628 @item @emph{Syntax}:
4629 @code{void _gfortran_caf_get (caf_token_t token, size_t offset,
4630 int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector,
4631 gfc_descriptor_t *dest, int src_kind, int dst_kind, bool may_require_tmp,
4634 @item @emph{Arguments}:
4635 @multitable @columnfractions .15 .70
4636 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4637 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
4638 shifted compared to the base address of the coarray.
4639 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4641 @item @var{dest} @tab intent(out) Array descriptor of the local array to store
4642 the data retrieved from the remote image
4643 @item @var{src} @tab intent(in) Array descriptor for the remote image for the
4644 bounds and the size. The @code{base_addr} shall not be accessed.
4645 @item @var{src_vector} @tab intent(in) If not NULL, it contains the vector
4646 subscript of the source array; the values are relative to the dimension
4647 triplet of the @var{src} argument.
4648 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4649 @item @var{src_kind} @tab intent(in) Kind of the source argument
4650 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4651 it is known at compile time that the @var{dest} and @var{src} either cannot
4652 overlap or overlap (fully or partially) such that walking @var{src} and
4653 @var{dest} in element wise element order (honoring the stride value) will not
4654 lead to wrong results. Otherwise, the value is @code{true}.
4655 @item @var{stat} @tab intent(out) When non-NULL give the result of the
4656 operation, i.e., zero on success and non-zero on error. When NULL and an error
4657 occurs, then an error message is printed and the program is terminated.
4661 It is permitted to have @var{image_index} equal the current image; the memory of
4662 the send-to and the send-from might (partially) overlap in that case. The
4663 implementation has to take care that it handles this case, e.g. using
4664 @code{memmove} which handles (partially) overlapping memory. If
4665 @var{may_require_tmp} is true, the library might additionally create a
4666 temporary variable, unless additional checks show that this is not required
4667 (e.g. because walking backward is possible or because both arrays are
4668 contiguous and @code{memmove} takes care of overlap issues).
4670 Note that the library has to handle numeric-type conversion and for strings,
4671 padding and different character kinds.
4675 @node _gfortran_caf_sendget
4676 @subsection @code{_gfortran_caf_sendget} --- Sending data between remote images
4677 @cindex Coarray, _gfortran_caf_sendget
4680 @item @emph{Description}:
4681 Called to send a scalar, an array section or a whole array from a remote image
4682 identified by the @var{src_image_index} to a remote image identified by the
4683 @var{dst_image_index}.
4685 @item @emph{Syntax}:
4686 @code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset,
4687 int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
4688 caf_token_t src_token, size_t src_offset, int src_image_index,
4689 gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind,
4690 bool may_require_tmp, int *stat)}
4692 @item @emph{Arguments}:
4693 @multitable @columnfractions .15 .70
4694 @item @var{dst_token} @tab intent(in) An opaque pointer identifying the
4695 destination coarray.
4696 @item @var{dst_offset} @tab intent(in) By which amount of bytes the actual data
4697 is shifted compared to the base address of the destination coarray.
4698 @item @var{dst_image_index} @tab intent(in) The ID of the destination remote
4699 image; must be a positive number.
4700 @item @var{dest} @tab intent(in) Array descriptor for the destination
4701 remote image for the bounds and the size. The @code{base_addr} shall not be
4703 @item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
4704 subscript of the destination array; the values are relative to the dimension
4705 triplet of the @var{dest} argument.
4706 @item @var{src_token} @tab intent(in) An opaque pointer identifying the source
4708 @item @var{src_offset} @tab intent(in) By which amount of bytes the actual data
4709 is shifted compared to the base address of the source coarray.
4710 @item @var{src_image_index} @tab intent(in) The ID of the source remote image;
4711 must be a positive number.
4712 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4713 transferred to the remote image.
4714 @item @var{src_vector} @tab intent(in) Array descriptor of the local array to
4715 be transferred to the remote image
4716 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4717 @item @var{src_kind} @tab intent(in) Kind of the source argument
4718 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4719 it is known at compile time that the @var{dest} and @var{src} either cannot
4720 overlap or overlap (fully or partially) such that walking @var{src} and
4721 @var{dest} in element wise element order (honoring the stride value) will not
4722 lead to wrong results. Otherwise, the value is @code{true}.
4723 @item @var{stat} @tab intent(out) when non-NULL give the result of the
4724 operation, i.e., zero on success and non-zero on error. When NULL and an error
4725 occurs, then an error message is printed and the program is terminated.
4729 It is permitted to have the same image index for both @var{src_image_index} and
4730 @var{dst_image_index}; the memory of the send-to and the send-from might
4731 (partially) overlap in that case. The implementation has to take care that it
4732 handles this case, e.g. using @code{memmove} which handles (partially)
4733 overlapping memory. If @var{may_require_tmp} is true, the library
4734 might additionally create a temporary variable, unless additional checks show
4735 that this is not required (e.g. because walking backward is possible or because
4736 both arrays are contiguous and @code{memmove} takes care of overlap issues).
4738 Note that the assignment of a scalar to an array is permitted. In addition,
4739 the library has to handle numeric-type conversion and for strings, padding and
4740 different character kinds.
4743 @node _gfortran_caf_send_by_ref
4744 @subsection @code{_gfortran_caf_send_by_ref} --- Sending data from a local image to a remote image with enhanced referencing options
4745 @cindex Coarray, _gfortran_caf_send_by_ref
4748 @item @emph{Description}:
4749 Called to send a scalar, an array section or a whole array from a local to a
4750 remote image identified by the @var{image_index}.
4752 @item @emph{Syntax}:
4753 @code{void _gfortran_caf_send_by_ref (caf_token_t token, int image_index,
4754 gfc_descriptor_t *src, caf_reference_t *refs, int dst_kind, int src_kind,
4755 bool may_require_tmp, bool dst_reallocatable, int *stat, int dst_type)}
4757 @item @emph{Arguments}:
4758 @multitable @columnfractions .15 .70
4759 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4760 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4762 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4763 transferred to the remote image
4764 @item @var{refs} @tab intent(in) The references on the remote array to store
4765 the data given by src. Guaranteed to have at least one entry.
4766 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4767 @item @var{src_kind} @tab intent(in) Kind of the source argument
4768 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4769 it is known at compile time that the @var{dest} and @var{src} either cannot
4770 overlap or overlap (fully or partially) such that walking @var{src} and
4771 @var{dest} in element wise element order (honoring the stride value) will not
4772 lead to wrong results. Otherwise, the value is @code{true}.
4773 @item @var{dst_reallocatable} @tab intent(in) Set when the destination is of
4774 allocatable or pointer type and the refs will allow reallocation, i.e., the ref
4775 is a full array or component ref.
4776 @item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the
4777 operation, i.e., zero on success and non-zero on error. When @code{NULL} and
4778 an error occurs, then an error message is printed and the program is terminated.
4779 @item @var{dst_type} @tab intent(in) Give the type of the destination. When
4780 the destination is not an array, than the precise type, e.g. of a component in
4781 a derived type, is not known, but provided here.
4785 It is permitted to have @var{image_index} equal the current image; the memory of
4786 the send-to and the send-from might (partially) overlap in that case. The
4787 implementation has to take care that it handles this case, e.g. using
4788 @code{memmove} which handles (partially) overlapping memory. If
4789 @var{may_require_tmp} is true, the library might additionally create a
4790 temporary variable, unless additional checks show that this is not required
4791 (e.g. because walking backward is possible or because both arrays are
4792 contiguous and @code{memmove} takes care of overlap issues).
4794 Note that the assignment of a scalar to an array is permitted. In addition,
4795 the library has to handle numeric-type conversion and for strings, padding
4796 and different character kinds.
4798 Because of the more complicated references possible some operations may be
4799 unsupported by certain libraries. The library is expected to issue a precise
4800 error message why the operation is not permitted.
4804 @node _gfortran_caf_get_by_ref
4805 @subsection @code{_gfortran_caf_get_by_ref} --- Getting data from a remote image using enhanced references
4806 @cindex Coarray, _gfortran_caf_get_by_ref
4809 @item @emph{Description}:
4810 Called to get a scalar, an array section or a whole array from a remote image
4811 identified by the @var{image_index}.
4813 @item @emph{Syntax}:
4814 @code{void _gfortran_caf_get_by_ref (caf_token_t token, int image_index,
4815 caf_reference_t *refs, gfc_descriptor_t *dst, int dst_kind, int src_kind,
4816 bool may_require_tmp, bool dst_reallocatable, int *stat, int src_type)}
4818 @item @emph{Arguments}:
4819 @multitable @columnfractions .15 .70
4820 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4821 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4823 @item @var{refs} @tab intent(in) The references to apply to the remote structure
4825 @item @var{dst} @tab intent(in) Array descriptor of the local array to store
4826 the data transferred from the remote image. May be reallocated where needed
4827 and when @var{DST_REALLOCATABLE} allows it.
4828 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4829 @item @var{src_kind} @tab intent(in) Kind of the source argument
4830 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4831 it is known at compile time that the @var{dest} and @var{src} either cannot
4832 overlap or overlap (fully or partially) such that walking @var{src} and
4833 @var{dest} in element wise element order (honoring the stride value) will not
4834 lead to wrong results. Otherwise, the value is @code{true}.
4835 @item @var{dst_reallocatable} @tab intent(in) Set when @var{DST} is of
4836 allocatable or pointer type and its refs allow reallocation, i.e., the full
4837 array or a component is referenced.
4838 @item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the
4839 operation, i.e., zero on success and non-zero on error. When @code{NULL} and an
4840 error occurs, then an error message is printed and the program is terminated.
4841 @item @var{src_type} @tab intent(in) Give the type of the source. When the
4842 source is not an array, than the precise type, e.g. of a component in a
4843 derived type, is not known, but provided here.
4847 It is permitted to have @code{image_index} equal the current image; the memory
4848 of the send-to and the send-from might (partially) overlap in that case. The
4849 implementation has to take care that it handles this case, e.g. using
4850 @code{memmove} which handles (partially) overlapping memory. If
4851 @var{may_require_tmp} is true, the library might additionally create a
4852 temporary variable, unless additional checks show that this is not required
4853 (e.g. because walking backward is possible or because both arrays are
4854 contiguous and @code{memmove} takes care of overlap issues).
4856 Note that the library has to handle numeric-type conversion and for strings,
4857 padding and different character kinds.
4859 Because of the more complicated references possible some operations may be
4860 unsupported by certain libraries. The library is expected to issue a precise
4861 error message why the operation is not permitted.
4865 @node _gfortran_caf_sendget_by_ref
4866 @subsection @code{_gfortran_caf_sendget_by_ref} --- Sending data between remote images using enhanced references on both sides
4867 @cindex Coarray, _gfortran_caf_sendget_by_ref
4870 @item @emph{Description}:
4871 Called to send a scalar, an array section or a whole array from a remote image
4872 identified by the @var{src_image_index} to a remote image identified by the
4873 @var{dst_image_index}.
4875 @item @emph{Syntax}:
4876 @code{void _gfortran_caf_sendget_by_ref (caf_token_t dst_token,
4877 int dst_image_index, caf_reference_t *dst_refs,
4878 caf_token_t src_token, int src_image_index, caf_reference_t *src_refs,
4879 int dst_kind, int src_kind, bool may_require_tmp, int *dst_stat,
4880 int *src_stat, int dst_type, int src_type)}
4882 @item @emph{Arguments}:
4883 @multitable @columnfractions .15 .70
4884 @item @var{dst_token} @tab intent(in) An opaque pointer identifying the
4885 destination coarray.
4886 @item @var{dst_image_index} @tab intent(in) The ID of the destination remote
4887 image; must be a positive number.
4888 @item @var{dst_refs} @tab intent(in) The references on the remote array to store
4889 the data given by the source. Guaranteed to have at least one entry.
4890 @item @var{src_token} @tab intent(in) An opaque pointer identifying the source
4892 @item @var{src_image_index} @tab intent(in) The ID of the source remote image;
4893 must be a positive number.
4894 @item @var{src_refs} @tab intent(in) The references to apply to the remote
4895 structure to get the data.
4896 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4897 @item @var{src_kind} @tab intent(in) Kind of the source argument
4898 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4899 it is known at compile time that the @var{dest} and @var{src} either cannot
4900 overlap or overlap (fully or partially) such that walking @var{src} and
4901 @var{dest} in element wise element order (honoring the stride value) will not
4902 lead to wrong results. Otherwise, the value is @code{true}.
4903 @item @var{dst_stat} @tab intent(out) when non-@code{NULL} give the result of
4904 the send-operation, i.e., zero on success and non-zero on error. When
4905 @code{NULL} and an error occurs, then an error message is printed and the
4906 program is terminated.
4907 @item @var{src_stat} @tab intent(out) When non-@code{NULL} give the result of
4908 the get-operation, i.e., zero on success and non-zero on error. When
4909 @code{NULL} and an error occurs, then an error message is printed and the
4910 program is terminated.
4911 @item @var{dst_type} @tab intent(in) Give the type of the destination. When
4912 the destination is not an array, than the precise type, e.g. of a component in
4913 a derived type, is not known, but provided here.
4914 @item @var{src_type} @tab intent(in) Give the type of the source. When the
4915 source is not an array, than the precise type, e.g. of a component in a
4916 derived type, is not known, but provided here.
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.
4933 Because of the more complicated references possible some operations may be
4934 unsupported by certain libraries. The library is expected to issue a precise
4935 error message why the operation is not permitted.
4939 @node _gfortran_caf_lock
4940 @subsection @code{_gfortran_caf_lock} --- Locking a lock variable
4941 @cindex Coarray, _gfortran_caf_lock
4944 @item @emph{Description}:
4945 Acquire a lock on the given image on a scalar locking variable or for the
4946 given array element for an array-valued variable. If the @var{aquired_lock}
4947 is @code{NULL}, the function returns after having obtained the lock. If it is
4948 non-@code{NULL}, then @var{acquired_lock} is assigned the value true (one) when
4949 the lock could be obtained and false (zero) otherwise. Locking a lock variable
4950 which has already been locked by the same image is an error.
4952 @item @emph{Syntax}:
4953 @code{void _gfortran_caf_lock (caf_token_t token, size_t index, int image_index,
4954 int *aquired_lock, int *stat, char *errmsg, size_t errmsg_len)}
4956 @item @emph{Arguments}:
4957 @multitable @columnfractions .15 .70
4958 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4959 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4960 scalars, it is always 0.
4961 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4963 @item @var{aquired_lock} @tab intent(out) If not NULL, it returns whether lock
4965 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
4966 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4967 an error message; may be NULL.
4968 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4972 This function is also called for critical blocks; for those, the array index
4973 is always zero and the image index is one. Libraries are permitted to use other
4974 images for critical-block locking variables.
4977 @node _gfortran_caf_unlock
4978 @subsection @code{_gfortran_caf_lock} --- Unlocking a lock variable
4979 @cindex Coarray, _gfortran_caf_unlock
4982 @item @emph{Description}:
4983 Release a lock on the given image on a scalar locking variable or for the
4984 given array element for an array-valued variable. Unlocking a lock variable
4985 which is unlocked or has been locked by a different image is an error.
4987 @item @emph{Syntax}:
4988 @code{void _gfortran_caf_unlock (caf_token_t token, size_t index, int image_index,
4989 int *stat, char *errmsg, size_t errmsg_len)}
4991 @item @emph{Arguments}:
4992 @multitable @columnfractions .15 .70
4993 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4994 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4995 scalars, it is always 0.
4996 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4998 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
5000 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5001 an error message; may be NULL.
5002 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5006 This function is also called for critical block; for those, the array index
5007 is always zero and the image index is one. Libraries are permitted to use other
5008 images for critical-block locking variables.
5011 @node _gfortran_caf_event_post
5012 @subsection @code{_gfortran_caf_event_post} --- Post an event
5013 @cindex Coarray, _gfortran_caf_event_post
5016 @item @emph{Description}:
5017 Increment the event count of the specified event variable.
5019 @item @emph{Syntax}:
5020 @code{void _gfortran_caf_event_post (caf_token_t token, size_t index,
5021 int image_index, int *stat, char *errmsg, size_t errmsg_len)}
5023 @item @emph{Arguments}:
5024 @multitable @columnfractions .15 .70
5025 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5026 @item @var{index} @tab intent(in) Array index; first array index is 0. For
5027 scalars, it is always 0.
5028 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5029 positive number; zero indicates the current image, when accessed noncoindexed.
5030 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
5031 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5032 an error message; may be NULL.
5033 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5037 This acts like an atomic add of one to the remote image's event variable.
5038 The statement is an image-control statement but does not imply sync memory.
5039 Still, all preceeding push communications of this image to the specified
5040 remote image have to be completed before @code{event_wait} on the remote
5046 @node _gfortran_caf_event_wait
5047 @subsection @code{_gfortran_caf_event_wait} --- Wait that an event occurred
5048 @cindex Coarray, _gfortran_caf_event_wait
5051 @item @emph{Description}:
5052 Wait until the event count has reached at least the specified
5053 @var{until_count}; if so, atomically decrement the event variable by this
5056 @item @emph{Syntax}:
5057 @code{void _gfortran_caf_event_wait (caf_token_t token, size_t index,
5058 int until_count, int *stat, char *errmsg, size_t errmsg_len)}
5060 @item @emph{Arguments}:
5061 @multitable @columnfractions .15 .70
5062 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5063 @item @var{index} @tab intent(in) Array index; first array index is 0. For
5064 scalars, it is always 0.
5065 @item @var{until_count} @tab intent(in) The number of events which have to be
5066 available before the function returns.
5067 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
5068 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5069 an error message; may be NULL.
5070 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5074 This function only operates on a local coarray. It acts like a loop checking
5075 atomically the value of the event variable, breaking if the value is greater
5076 or equal the requested number of counts. Before the function returns, the
5077 event variable has to be decremented by the requested @var{until_count} value.
5078 A possible implementation would be a busy loop for a certain number of spins
5079 (possibly depending on the number of threads relative to the number of available
5080 cores) followed by another waiting strategy such as a sleeping wait (possibly
5081 with an increasing number of sleep time) or, if possible, a futex wait.
5083 The statement is an image-control statement but does not imply sync memory.
5084 Still, all preceeding push communications of this image to the specified
5085 remote image have to be completed before @code{event_wait} on the remote
5091 @node _gfortran_caf_event_query
5092 @subsection @code{_gfortran_caf_event_query} --- Query event count
5093 @cindex Coarray, _gfortran_caf_event_query
5096 @item @emph{Description}:
5097 Return the event count of the specified event variable.
5099 @item @emph{Syntax}:
5100 @code{void _gfortran_caf_event_query (caf_token_t token, size_t index,
5101 int image_index, int *count, int *stat)}
5103 @item @emph{Arguments}:
5104 @multitable @columnfractions .15 .70
5105 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5106 @item @var{index} @tab intent(in) Array index; first array index is 0. For
5107 scalars, it is always 0.
5108 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5109 positive number; zero indicates the current image when accessed noncoindexed.
5110 @item @var{count} @tab intent(out) The number of events currently posted to
5112 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
5116 The typical use is to check the local event variable to only call
5117 @code{event_wait} when the data is available. However, a coindexed variable
5118 is permitted; there is no ordering or synchronization implied. It acts like
5119 an atomic fetch of the value of the event variable.
5124 @node _gfortran_caf_sync_all
5125 @subsection @code{_gfortran_caf_sync_all} --- All-image barrier
5126 @cindex Coarray, _gfortran_caf_sync_all
5129 @item @emph{Description}:
5130 Synchronization of all images in the current team; the program only continues
5131 on a given image after this function has been called on all images of the
5132 current team. Additionally, it ensures that all pending data transfers of
5133 previous segment have completed.
5135 @item @emph{Syntax}:
5136 @code{void _gfortran_caf_sync_all (int *stat, char *errmsg, size_t errmsg_len)}
5138 @item @emph{Arguments}:
5139 @multitable @columnfractions .15 .70
5140 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5141 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5142 an error message; may be NULL.
5143 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5149 @node _gfortran_caf_sync_images
5150 @subsection @code{_gfortran_caf_sync_images} --- Barrier for selected images
5151 @cindex Coarray, _gfortran_caf_sync_images
5154 @item @emph{Description}:
5155 Synchronization between the specified images; the program only continues on a
5156 given image after this function has been called on all images specified for
5157 that image. Note that one image can wait for all other images in the current
5158 team (e.g. via @code{sync images(*)}) while those only wait for that specific
5159 image. Additionally, @code{sync images} ensures that all pending data
5160 transfers of previous segments have completed.
5162 @item @emph{Syntax}:
5163 @code{void _gfortran_caf_sync_images (int count, int images[], int *stat,
5164 char *errmsg, size_t errmsg_len)}
5166 @item @emph{Arguments}:
5167 @multitable @columnfractions .15 .70
5168 @item @var{count} @tab intent(in) The number of images which are provided in
5169 the next argument. For a zero-sized array, the value is zero. For
5170 @code{sync images (*)}, the value is @math{-1}.
5171 @item @var{images} @tab intent(in) An array with the images provided by the
5172 user. If @var{count} is zero, a NULL pointer is passed.
5173 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5174 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5175 an error message; may be NULL.
5176 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5182 @node _gfortran_caf_sync_memory
5183 @subsection @code{_gfortran_caf_sync_memory} --- Wait for completion of segment-memory operations
5184 @cindex Coarray, _gfortran_caf_sync_memory
5187 @item @emph{Description}:
5188 Acts as optimization barrier between different segments. It also ensures that
5189 all pending memory operations of this image have been completed.
5191 @item @emph{Syntax}:
5192 @code{void _gfortran_caf_sync_memory (int *stat, char *errmsg, size_t errmsg_len)}
5194 @item @emph{Arguments}:
5195 @multitable @columnfractions .15 .70
5196 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5197 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5198 an error message; may be NULL.
5199 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5202 @item @emph{NOTE} A simple implementation could be
5203 @code{__asm__ __volatile__ ("":::"memory")} to prevent code movements.
5208 @node _gfortran_caf_error_stop
5209 @subsection @code{_gfortran_caf_error_stop} --- Error termination with exit code
5210 @cindex Coarray, _gfortran_caf_error_stop
5213 @item @emph{Description}:
5214 Invoked for an @code{ERROR STOP} statement which has an integer argument. The
5215 function should terminate the program with the specified exit code.
5218 @item @emph{Syntax}:
5219 @code{void _gfortran_caf_error_stop (int error)}
5221 @item @emph{Arguments}:
5222 @multitable @columnfractions .15 .70
5223 @item @var{error} @tab intent(in) The exit status to be used.
5229 @node _gfortran_caf_error_stop_str
5230 @subsection @code{_gfortran_caf_error_stop_str} --- Error termination with string
5231 @cindex Coarray, _gfortran_caf_error_stop_str
5234 @item @emph{Description}:
5235 Invoked for an @code{ERROR STOP} statement which has a string as argument. The
5236 function should terminate the program with a nonzero-exit code.
5238 @item @emph{Syntax}:
5239 @code{void _gfortran_caf_error_stop (const char *string, size_t len)}
5241 @item @emph{Arguments}:
5242 @multitable @columnfractions .15 .70
5243 @item @var{string} @tab intent(in) the error message (not zero terminated)
5244 @item @var{len} @tab intent(in) the length of the string
5250 @node _gfortran_caf_fail_image
5251 @subsection @code{_gfortran_caf_fail_image} --- Mark the image failed and end its execution
5252 @cindex Coarray, _gfortran_caf_fail_image
5255 @item @emph{Description}:
5256 Invoked for an @code{FAIL IMAGE} statement. The function should terminate the
5259 @item @emph{Syntax}:
5260 @code{void _gfortran_caf_fail_image ()}
5263 This function follows TS18508.
5268 @node _gfortran_caf_atomic_define
5269 @subsection @code{_gfortran_caf_atomic_define} --- Atomic variable assignment
5270 @cindex Coarray, _gfortran_caf_atomic_define
5273 @item @emph{Description}:
5274 Assign atomically a value to an integer or logical variable.
5276 @item @emph{Syntax}:
5277 @code{void _gfortran_caf_atomic_define (caf_token_t token, size_t offset,
5278 int image_index, void *value, int *stat, int type, int kind)}
5280 @item @emph{Arguments}:
5281 @multitable @columnfractions .15 .70
5282 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5283 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5284 shifted compared to the base address of the coarray.
5285 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5286 positive number; zero indicates the current image when used noncoindexed.
5287 @item @var{value} @tab intent(in) the value to be assigned, passed by reference
5288 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5289 @item @var{type} @tab intent(in) The data type, i.e. @code{BT_INTEGER} (1) or
5290 @code{BT_LOGICAL} (2).
5291 @item @var{kind} @tab intent(in) The kind value (only 4; always @code{int})
5297 @node _gfortran_caf_atomic_ref
5298 @subsection @code{_gfortran_caf_atomic_ref} --- Atomic variable reference
5299 @cindex Coarray, _gfortran_caf_atomic_ref
5302 @item @emph{Description}:
5303 Reference atomically a value of a kind-4 integer or logical variable.
5305 @item @emph{Syntax}:
5306 @code{void _gfortran_caf_atomic_ref (caf_token_t token, size_t offset,
5307 int image_index, void *value, int *stat, int type, int kind)}
5309 @item @emph{Arguments}:
5310 @multitable @columnfractions .15 .70
5311 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5312 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5313 shifted compared to the base address of the coarray.
5314 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5315 positive number; zero indicates the current image when used noncoindexed.
5316 @item @var{value} @tab intent(out) The variable assigned the atomically
5317 referenced variable.
5318 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5319 @item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
5320 @code{BT_LOGICAL} (2).
5321 @item @var{kind} @tab The kind value (only 4; always @code{int})
5327 @node _gfortran_caf_atomic_cas
5328 @subsection @code{_gfortran_caf_atomic_cas} --- Atomic compare and swap
5329 @cindex Coarray, _gfortran_caf_atomic_cas
5332 @item @emph{Description}:
5333 Atomic compare and swap of a kind-4 integer or logical variable. Assigns
5334 atomically the specified value to the atomic variable, if the latter has
5335 the value specified by the passed condition value.
5337 @item @emph{Syntax}:
5338 @code{void _gfortran_caf_atomic_cas (caf_token_t token, size_t offset,
5339 int image_index, void *old, void *compare, void *new_val, int *stat,
5340 int type, int kind)}
5342 @item @emph{Arguments}:
5343 @multitable @columnfractions .15 .70
5344 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5345 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5346 shifted compared to the base address of the coarray.
5347 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5348 positive number; zero indicates the current image when used noncoindexed.
5349 @item @var{old} @tab intent(out) The value which the atomic variable had
5350 just before the cas operation.
5351 @item @var{compare} @tab intent(in) The value used for comparision.
5352 @item @var{new_val} @tab intent(in) The new value for the atomic variable,
5353 assigned to the atomic variable, if @code{compare} equals the value of the
5355 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5356 @item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or
5357 @code{BT_LOGICAL} (2).
5358 @item @var{kind} @tab intent(in) The kind value (only 4; always @code{int})
5364 @node _gfortran_caf_atomic_op
5365 @subsection @code{_gfortran_caf_atomic_op} --- Atomic operation
5366 @cindex Coarray, _gfortran_caf_atomic_op
5369 @item @emph{Description}:
5370 Apply an operation atomically to an atomic integer or logical variable.
5371 After the operation, @var{old} contains the value just before the operation,
5372 which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the @code{value} to
5373 the atomic integer variable or does a bitwise AND, OR or exclusive OR
5374 between the atomic variable and @var{value}; the result is then stored in the
5377 @item @emph{Syntax}:
5378 @code{void _gfortran_caf_atomic_op (int op, caf_token_t token, size_t offset,
5379 int image_index, void *value, void *old, int *stat, int type, int kind)}
5381 @item @emph{Arguments}:
5382 @multitable @columnfractions .15 .70
5383 @item @var{op} @tab intent(in) the operation to be performed; possible values
5384 @code{GFC_CAF_ATOMIC_ADD} (1), @code{GFC_CAF_ATOMIC_AND} (2),
5385 @code{GFC_CAF_ATOMIC_OR} (3), @code{GFC_CAF_ATOMIC_XOR} (4).
5386 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5387 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5388 shifted compared to the base address of the coarray.
5389 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5390 positive number; zero indicates the current image when used noncoindexed.
5391 @item @var{old} @tab intent(out) The value which the atomic variable had
5392 just before the atomic operation.
5393 @item @var{val} @tab intent(in) The new value for the atomic variable,
5394 assigned to the atomic variable, if @code{compare} equals the value of the
5396 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5397 @item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or
5398 @code{BT_LOGICAL} (2)
5399 @item @var{kind} @tab intent(in) the kind value (only 4; always @code{int})
5406 @node _gfortran_caf_co_broadcast
5407 @subsection @code{_gfortran_caf_co_broadcast} --- Sending data to all images
5408 @cindex Coarray, _gfortran_caf_co_broadcast
5411 @item @emph{Description}:
5412 Distribute a value from a given image to all other images in the team. Has to
5413 be called collectively.
5415 @item @emph{Syntax}:
5416 @code{void _gfortran_caf_co_broadcast (gfc_descriptor_t *a,
5417 int source_image, int *stat, char *errmsg, size_t errmsg_len)}
5419 @item @emph{Arguments}:
5420 @multitable @columnfractions .15 .70
5421 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5422 broadcasted (on @var{source_image}) or to be received (other images).
5423 @item @var{source_image} @tab intent(in) The ID of the image from which the
5424 data should be broadcasted.
5425 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5426 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5427 an error message; may be NULL.
5428 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg.
5434 @node _gfortran_caf_co_max
5435 @subsection @code{_gfortran_caf_co_max} --- Collective maximum reduction
5436 @cindex Coarray, _gfortran_caf_co_max
5439 @item @emph{Description}:
5440 Calculates for each array element of the variable @var{a} the maximum
5441 value for that element in the current team; if @var{result_image} has the
5442 value 0, the result shall be stored on all images, otherwise, only on the
5443 specified image. This function operates on numeric values and character
5446 @item @emph{Syntax}:
5447 @code{void _gfortran_caf_co_max (gfc_descriptor_t *a, int result_image,
5448 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5450 @item @emph{Arguments}:
5451 @multitable @columnfractions .15 .70
5452 @item @var{a} @tab intent(inout) An array descriptor for the data to be
5453 processed. On the destination image(s) the result overwrites the old content.
5454 @item @var{result_image} @tab intent(in) The ID of the image to which the
5455 reduced value should be copied to; if zero, it has to be copied to all images.
5456 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5457 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5458 an error message; may be NULL.
5459 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5460 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5464 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5465 all images except of the specified one become undefined; hence, the library may
5471 @node _gfortran_caf_co_min
5472 @subsection @code{_gfortran_caf_co_min} --- Collective minimum reduction
5473 @cindex Coarray, _gfortran_caf_co_min
5476 @item @emph{Description}:
5477 Calculates for each array element of the variable @var{a} the minimum
5478 value for that element in the current team; if @var{result_image} has the
5479 value 0, the result shall be stored on all images, otherwise, only on the
5480 specified image. This function operates on numeric values and character
5483 @item @emph{Syntax}:
5484 @code{void _gfortran_caf_co_min (gfc_descriptor_t *a, int result_image,
5485 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5487 @item @emph{Arguments}:
5488 @multitable @columnfractions .15 .70
5489 @item @var{a} @tab intent(inout) An array descriptor for the data to be
5490 processed. On the destination image(s) the result overwrites the old content.
5491 @item @var{result_image} @tab intent(in) The ID of the image to which the
5492 reduced value should be copied to; if zero, it has to be copied to all images.
5493 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5494 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5495 an error message; may be NULL.
5496 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5497 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5501 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5502 all images except of the specified one become undefined; hence, the library may
5508 @node _gfortran_caf_co_sum
5509 @subsection @code{_gfortran_caf_co_sum} --- Collective summing reduction
5510 @cindex Coarray, _gfortran_caf_co_sum
5513 @item @emph{Description}:
5514 Calculates for each array element of the variable @var{a} the sum of all
5515 values for that element in the current team; if @var{result_image} has the
5516 value 0, the result shall be stored on all images, otherwise, only on the
5517 specified image. This function operates on numeric values only.
5519 @item @emph{Syntax}:
5520 @code{void _gfortran_caf_co_sum (gfc_descriptor_t *a, int result_image,
5521 int *stat, char *errmsg, size_t errmsg_len)}
5523 @item @emph{Arguments}:
5524 @multitable @columnfractions .15 .70
5525 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5526 processed. On the destination image(s) the result overwrites the old content.
5527 @item @var{result_image} @tab intent(in) The ID of the image to which the
5528 reduced value should be copied to; if zero, it has to be copied to all images.
5529 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5530 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5531 an error message; may be NULL.
5532 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5536 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5537 all images except of the specified one become undefined; hence, the library may
5543 @node _gfortran_caf_co_reduce
5544 @subsection @code{_gfortran_caf_co_reduce} --- Generic collective reduction
5545 @cindex Coarray, _gfortran_caf_co_reduce
5548 @item @emph{Description}:
5549 Calculates for each array element of the variable @var{a} the reduction
5550 value for that element in the current team; if @var{result_image} has the
5551 value 0, the result shall be stored on all images, otherwise, only on the
5552 specified image. The @var{opr} is a pure function doing a mathematically
5553 commutative and associative operation.
5555 The @var{opr_flags} denote the following; the values are bitwise ored.
5556 @code{GFC_CAF_BYREF} (1) if the result should be returned
5557 by reference; @code{GFC_CAF_HIDDENLEN} (2) whether the result and argument
5558 string lengths shall be specified as hidden arguments;
5559 @code{GFC_CAF_ARG_VALUE} (4) whether the arguments shall be passed by value,
5560 @code{GFC_CAF_ARG_DESC} (8) whether the arguments shall be passed by descriptor.
5563 @item @emph{Syntax}:
5564 @code{void _gfortran_caf_co_reduce (gfc_descriptor_t *a,
5565 void * (*opr) (void *, void *), int opr_flags, int result_image,
5566 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5568 @item @emph{Arguments}:
5569 @multitable @columnfractions .15 .70
5570 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5571 processed. On the destination image(s) the result overwrites the old content.
5572 @item @var{opr} @tab intent(in) Function pointer to the reduction function
5573 @item @var{opr_flags} @tab intent(in) Flags regarding the reduction function
5574 @item @var{result_image} @tab intent(in) The ID of the image to which the
5575 reduced value should be copied to; if zero, it has to be copied to all images.
5576 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5577 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5578 an error message; may be NULL.
5579 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5580 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5584 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5585 all images except of the specified one become undefined; hence, the library may
5588 For character arguments, the result is passed as first argument, followed
5589 by the result string length, next come the two string arguments, followed
5590 by the two hidden string length arguments. With C binding, there are no hidden
5591 arguments and by-reference passing and either only a single character is passed
5592 or an array descriptor.
5596 @c Intrinsic Procedures
5597 @c ---------------------------------------------------------------------
5599 @include intrinsic.texi
5606 @c ---------------------------------------------------------------------
5608 @c ---------------------------------------------------------------------
5611 @unnumbered Contributing
5612 @cindex Contributing
5614 Free software is only possible if people contribute to efforts
5616 We're always in need of more people helping out with ideas
5617 and comments, writing documentation and contributing code.
5619 If you want to contribute to GNU Fortran,
5620 have a look at the long lists of projects you can take on.
5621 Some of these projects are small,
5622 some of them are large;
5623 some are completely orthogonal to the rest of what is
5624 happening on GNU Fortran,
5625 but others are ``mainstream'' projects in need of enthusiastic hackers.
5626 All of these projects are important!
5627 We will eventually get around to the things here,
5628 but they are also things doable by someone who is willing and able.
5633 * Proposed Extensions::
5638 @section Contributors to GNU Fortran
5639 @cindex Contributors
5643 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
5644 also the initiator of the whole project. Thanks Andy!
5645 Most of the interface with GCC was written by @emph{Paul Brook}.
5647 The following individuals have contributed code and/or
5648 ideas and significant help to the GNU Fortran project
5649 (in alphabetical order):
5652 @item Janne Blomqvist
5653 @item Steven Bosscher
5656 @item Fran@,{c}ois-Xavier Coudert
5660 @item Bernhard Fischer
5662 @item Richard Guenther
5663 @item Richard Henderson
5664 @item Katherine Holcomb
5666 @item Niels Kristian Bech Jensen
5667 @item Steven Johnson
5668 @item Steven G. Kargl
5676 @item Christopher D. Rickett
5677 @item Richard Sandiford
5678 @item Tobias Schl@"uter
5687 The following people have contributed bug reports,
5688 smaller or larger patches,
5689 and much needed feedback and encouragement for the
5690 GNU Fortran project:
5694 @item Dominique d'Humi@`eres
5696 @item Erik Schnetter
5697 @item Joost VandeVondele
5700 Many other individuals have helped debug,
5701 test and improve the GNU Fortran compiler over the past few years,
5702 and we welcome you to do the same!
5703 If you already have done so,
5704 and you would like to see your name listed in the
5705 list above, please contact us.
5713 @item Help build the test suite
5714 Solicit more code for donation to the test suite: the more extensive the
5715 testsuite, the smaller the risk of breaking things in the future! We can
5716 keep code private on request.
5718 @item Bug hunting/squishing
5719 Find bugs and write more test cases! Test cases are especially very
5720 welcome, because it allows us to concentrate on fixing bugs instead of
5721 isolating them. Going through the bugzilla database at
5722 @url{https://gcc.gnu.org/@/bugzilla/} to reduce testcases posted there and
5723 add more information (for example, for which version does the testcase
5724 work, for which versions does it fail?) is also very helpful.
5729 @node Proposed Extensions
5730 @section Proposed Extensions
5732 Here's a list of proposed extensions for the GNU Fortran compiler, in no particular
5733 order. Most of these are necessary to be fully compatible with
5734 existing Fortran compilers, but they are not part of the official
5735 J3 Fortran 95 standard.
5737 @subsection Compiler extensions:
5740 User-specified alignment rules for structures.
5743 Automatically extend single precision constants to double.
5746 Compile code that conserves memory by dynamically allocating common and
5747 module storage either on stack or heap.
5750 Compile flag to generate code for array conformance checking (suggest -CC).
5753 User control of symbol names (underscores, etc).
5756 Compile setting for maximum size of stack frame size before spilling
5757 parts to static or heap.
5760 Flag to force local variables into static space.
5763 Flag to force local variables onto stack.
5767 @subsection Environment Options
5770 Pluggable library modules for random numbers, linear algebra.
5771 LA should use BLAS calling conventions.
5774 Environment variables controlling actions on arithmetic exceptions like
5775 overflow, underflow, precision loss---Generate NaN, abort, default.
5779 Set precision for fp units that support it (i387).
5782 Variable for setting fp rounding mode.
5785 Variable to fill uninitialized variables with a user-defined bit
5789 Environment variable controlling filename that is opened for that unit
5793 Environment variable to clear/trash memory being freed.
5796 Environment variable to control tracing of allocations and frees.
5799 Environment variable to display allocated memory at normal program end.
5802 Environment variable for filename for * IO-unit.
5805 Environment variable for temporary file directory.
5808 Environment variable forcing standard output to be line buffered (Unix).
5813 @c ---------------------------------------------------------------------
5814 @c GNU General Public License
5815 @c ---------------------------------------------------------------------
5817 @include gpl_v3.texi
5821 @c ---------------------------------------------------------------------
5822 @c GNU Free Documentation License
5823 @c ---------------------------------------------------------------------
5829 @c ---------------------------------------------------------------------
5830 @c Funding Free Software
5831 @c ---------------------------------------------------------------------
5833 @include funding.texi
5835 @c ---------------------------------------------------------------------
5837 @c ---------------------------------------------------------------------
5840 @unnumbered Option Index
5841 @command{gfortran}'s command line options are indexed here without any
5842 initial @samp{-} or @samp{--}. Where an option has both positive and
5843 negative forms (such as -foption and -fno-option), relevant entries in
5844 the manual are indexed under the most appropriate form; it may sometimes
5845 be useful to look up both forms.
5849 @unnumbered Keyword Index