1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set copyrights-gfortran 1999-2015
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 2003 and 2008 status:: Fortran 2003 and 2008 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 and Fortran 2008 standards, and
247 several vendor extensions. The development goal is to provide the
252 Read a user's program,
253 stored in a file and containing instructions written
254 in Fortran 77, Fortran 90, Fortran 95, Fortran 2003 or Fortran 2008.
255 This file contains @dfn{source code}.
258 Translate the user's program into instructions a computer
259 can carry out more quickly than it takes to translate the
260 instructions in the first
261 place. The result after compilation of a program is
263 code designed to be efficiently translated and processed
264 by a machine such as your computer.
265 Humans usually are not as good writing machine code
266 as they are at writing Fortran (or C++, Ada, or Java),
267 because it is easy to make tiny mistakes writing machine code.
270 Provide the user with information about the reasons why
271 the compiler is unable to create a binary from the source code.
272 Usually this will be the case if the source code is flawed.
273 The Fortran 90 standard requires that the compiler can point out
274 mistakes to the user.
275 An incorrect usage of the language causes an @dfn{error message}.
277 The compiler will also attempt to diagnose cases where the
278 user's program contains a correct usage of the language,
279 but instructs the computer to do something questionable.
280 This kind of diagnostics message is called a @dfn{warning message}.
283 Provide optional information about the translation passes
284 from the source code to machine code.
285 This can help a user of the compiler to find the cause of
286 certain bugs which may not be obvious in the source code,
287 but may be more easily found at a lower level compiler output.
288 It also helps developers to find bugs in the compiler itself.
291 Provide information in the generated machine code that can
292 make it easier to find bugs in the program (using a debugging tool,
293 called a @dfn{debugger}, such as the GNU Debugger @command{gdb}).
296 Locate and gather machine code already generated to
297 perform actions requested by statements in the user's program.
298 This machine code is organized into @dfn{modules} and is located
299 and @dfn{linked} to the user program.
302 The GNU Fortran compiler consists of several components:
306 A version of the @command{gcc} command
307 (which also might be installed as the system's @command{cc} command)
308 that also understands and accepts Fortran source code.
309 The @command{gcc} command is the @dfn{driver} program for
310 all the languages in the GNU Compiler Collection (GCC);
312 you can compile the source code of any language for
313 which a front end is available in GCC.
316 The @command{gfortran} command itself,
317 which also might be installed as the
318 system's @command{f95} command.
319 @command{gfortran} is just another driver program,
320 but specifically for the Fortran compiler only.
321 The difference with @command{gcc} is that @command{gfortran}
322 will automatically link the correct libraries to your program.
325 A collection of run-time libraries.
326 These libraries contain the machine code needed to support
327 capabilities of the Fortran language that are not directly
328 provided by the machine code generated by the
329 @command{gfortran} compilation phase,
330 such as intrinsic functions and subroutines,
331 and routines for interaction with files and the operating system.
332 @c and mechanisms to spawn,
333 @c unleash and pause threads in parallelized code.
336 The Fortran compiler itself, (@command{f951}).
337 This is the GNU Fortran parser and code generator,
338 linked to and interfaced with the GCC backend library.
339 @command{f951} ``translates'' the source code to
340 assembler code. You would typically not use this
342 instead, the @command{gcc} or @command{gfortran} driver
343 programs will call it for you.
347 @c ---------------------------------------------------------------------
348 @c GNU Fortran and GCC
349 @c ---------------------------------------------------------------------
351 @node GNU Fortran and GCC
352 @section GNU Fortran and GCC
353 @cindex GNU Compiler Collection
356 GNU Fortran is a part of GCC, the @dfn{GNU Compiler Collection}. GCC
357 consists of a collection of front ends for various languages, which
358 translate the source code into a language-independent form called
359 @dfn{GENERIC}. This is then processed by a common middle end which
360 provides optimization, and then passed to one of a collection of back
361 ends which generate code for different computer architectures and
364 Functionally, this is implemented with a driver program (@command{gcc})
365 which provides the command-line interface for the compiler. It calls
366 the relevant compiler front-end program (e.g., @command{f951} for
367 Fortran) for each file in the source code, and then calls the assembler
368 and linker as appropriate to produce the compiled output. In a copy of
369 GCC which has been compiled with Fortran language support enabled,
370 @command{gcc} will recognize files with @file{.f}, @file{.for}, @file{.ftn},
371 @file{.f90}, @file{.f95}, @file{.f03} and @file{.f08} extensions as
372 Fortran source code, and compile it accordingly. A @command{gfortran}
373 driver program is also provided, which is identical to @command{gcc}
374 except that it automatically links the Fortran runtime libraries into the
377 Source files with @file{.f}, @file{.for}, @file{.fpp}, @file{.ftn}, @file{.F},
378 @file{.FOR}, @file{.FPP}, and @file{.FTN} extensions are treated as fixed form.
379 Source files with @file{.f90}, @file{.f95}, @file{.f03}, @file{.f08},
380 @file{.F90}, @file{.F95}, @file{.F03} and @file{.F08} extensions are
381 treated as free form. The capitalized versions of either form are run
382 through preprocessing. Source files with the lower case @file{.fpp}
383 extension are also run through preprocessing.
385 This manual specifically documents the Fortran front end, which handles
386 the programming language's syntax and semantics. The aspects of GCC
387 which relate to the optimization passes and the back-end code generation
388 are documented in the GCC manual; see
389 @ref{Top,,Introduction,gcc,Using the GNU Compiler Collection (GCC)}.
390 The two manuals together provide a complete reference for the GNU
394 @c ---------------------------------------------------------------------
395 @c Preprocessing and conditional compilation
396 @c ---------------------------------------------------------------------
398 @node Preprocessing and conditional compilation
399 @section Preprocessing and conditional compilation
402 @cindex Conditional compilation
403 @cindex Preprocessing
404 @cindex preprocessor, include file handling
406 Many Fortran compilers including GNU Fortran allow passing the source code
407 through a C preprocessor (CPP; sometimes also called the Fortran preprocessor,
408 FPP) to allow for conditional compilation. In the case of GNU Fortran,
409 this is the GNU C Preprocessor in the traditional mode. On systems with
410 case-preserving file names, the preprocessor is automatically invoked if the
411 filename extension is @file{.F}, @file{.FOR}, @file{.FTN}, @file{.fpp},
412 @file{.FPP}, @file{.F90}, @file{.F95}, @file{.F03} or @file{.F08}. To manually
413 invoke the preprocessor on any file, use @option{-cpp}, to disable
414 preprocessing on files where the preprocessor is run automatically, use
417 If a preprocessed file includes another file with the Fortran @code{INCLUDE}
418 statement, the included file is not preprocessed. To preprocess included
419 files, use the equivalent preprocessor statement @code{#include}.
421 If GNU Fortran invokes the preprocessor, @code{__GFORTRAN__}
422 is defined and @code{__GNUC__}, @code{__GNUC_MINOR__} and
423 @code{__GNUC_PATCHLEVEL__} can be used to determine the version of the
424 compiler. See @ref{Top,,Overview,cpp,The C Preprocessor} for details.
426 While CPP is the de-facto standard for preprocessing Fortran code,
427 Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines
428 Conditional Compilation, which is not widely used and not directly
429 supported by the GNU Fortran compiler. You can use the program coco
430 to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}).
433 @c ---------------------------------------------------------------------
434 @c GNU Fortran and G77
435 @c ---------------------------------------------------------------------
437 @node GNU Fortran and G77
438 @section GNU Fortran and G77
440 @cindex @command{g77}
442 The GNU Fortran compiler is the successor to @command{g77}, the Fortran
443 77 front end included in GCC prior to version 4. It is an entirely new
444 program that has been designed to provide Fortran 95 support and
445 extensibility for future Fortran language standards, as well as providing
446 backwards compatibility for Fortran 77 and nearly all of the GNU language
447 extensions supported by @command{g77}.
450 @c ---------------------------------------------------------------------
452 @c ---------------------------------------------------------------------
455 @section Project Status
458 As soon as @command{gfortran} can parse all of the statements correctly,
459 it will be in the ``larva'' state.
460 When we generate code, the ``puppa'' state.
461 When @command{gfortran} is done,
462 we'll see if it will be a beautiful butterfly,
463 or just a big bug....
465 --Andy Vaught, April 2000
468 The start of the GNU Fortran 95 project was announced on
469 the GCC homepage in March 18, 2000
470 (even though Andy had already been working on it for a while,
473 The GNU Fortran compiler is able to compile nearly all
474 standard-compliant Fortran 95, Fortran 90, and Fortran 77 programs,
475 including a number of standard and non-standard extensions, and can be
476 used on real-world programs. In particular, the supported extensions
477 include OpenMP, Cray-style pointers, and several Fortran 2003 and Fortran
478 2008 features, including TR 15581. However, it is still under
479 development and has a few remaining rough edges.
480 There also is initial support for OpenACC.
481 Note that this is an experimental feature, incomplete, and subject to
482 change in future versions of GCC. See
483 @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
485 At present, the GNU Fortran compiler passes the
486 @uref{http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html,
487 NIST Fortran 77 Test Suite}, and produces acceptable results on the
488 @uref{http://www.netlib.org/lapack/faq.html#1.21, LAPACK Test Suite}.
489 It also provides respectable performance on
490 the @uref{http://www.polyhedron.com/fortran-compiler-comparisons/polyhedron-benchmark-suite,
492 compiler benchmarks} and the
493 @uref{http://www.netlib.org/benchmark/livermore,
494 Livermore Fortran Kernels test}. It has been used to compile a number of
495 large real-world programs, including
496 @uref{http://hirlam.org/, the HARMONIE and HIRLAM weather forecasting code} and
497 @uref{http://physical-chemistry.scb.uwa.edu.au/tonto/wiki/index.php/Main_Page,
498 the Tonto quantum chemistry package}; see
499 @url{https://gcc.gnu.org/@/wiki/@/GfortranApps} for an extended list.
501 Among other things, the GNU Fortran compiler is intended as a replacement
502 for G77. At this point, nearly all programs that could be compiled with
503 G77 can be compiled with GNU Fortran, although there are a few minor known
506 The primary work remaining to be done on GNU Fortran falls into three
507 categories: bug fixing (primarily regarding the treatment of invalid code
508 and providing useful error messages), improving the compiler optimizations
509 and the performance of compiled code, and extending the compiler to support
510 future standards---in particular, Fortran 2003 and Fortran 2008.
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 (Fortran
531 2003), ISO/IEC 1539-1:2010 (Fortran 2008), the Technical Specification
532 @code{Further Interoperability of Fortran with C} (ISO/IEC TS 29113:2012).
533 Full support of those standards and future Fortran standards is planned.
534 The current status of the support is can be found in the
535 @ref{Fortran 2003 status}, @ref{Fortran 2008 status}, @ref{TS 29113 status}
536 and @ref{TS 18508 status} sections of the documentation.
538 Additionally, the GNU Fortran compilers supports the OpenMP specification
539 (version 4.0, @url{http://openmp.org/@/wp/@/openmp-specifications/}).
540 There also is initial support for the OpenACC specification (targeting
541 version 2.0, @uref{http://www.openacc.org/}).
542 Note that this is an experimental feature, incomplete, and subject to
543 change in future versions of GCC. See
544 @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
546 @node Varying Length Character Strings
547 @subsection Varying Length Character Strings
548 @cindex Varying length character strings
549 @cindex Varying length strings
550 @cindex strings, varying length
552 The Fortran 95 standard specifies in Part 2 (ISO/IEC 1539-2:2000)
553 varying length character strings. While GNU Fortran currently does not
554 support such strings directly, there exist two Fortran implementations
555 for them, which work with GNU Fortran. They can be found at
556 @uref{http://www.fortran.com/@/iso_varying_string.f95} and at
557 @uref{ftp://ftp.nag.co.uk/@/sc22wg5/@/ISO_VARYING_STRING/}.
559 Deferred-length character strings of Fortran 2003 supports part of
560 the features of @code{ISO_VARYING_STRING} and should be considered as
561 replacement. (Namely, allocatable or pointers of the type
562 @code{character(len=:)}.)
565 @c =====================================================================
566 @c PART I: INVOCATION REFERENCE
567 @c =====================================================================
570 \part{I}{Invoking GNU Fortran}
573 @c ---------------------------------------------------------------------
575 @c ---------------------------------------------------------------------
580 @c ---------------------------------------------------------------------
582 @c ---------------------------------------------------------------------
585 @chapter Runtime: Influencing runtime behavior with environment variables
586 @cindex environment variable
588 The behavior of the @command{gfortran} can be influenced by
589 environment variables.
591 Malformed environment variables are silently ignored.
594 * TMPDIR:: Directory for scratch files
595 * GFORTRAN_STDIN_UNIT:: Unit number for standard input
596 * GFORTRAN_STDOUT_UNIT:: Unit number for standard output
597 * GFORTRAN_STDERR_UNIT:: Unit number for standard error
598 * GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units.
599 * GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units.
600 * GFORTRAN_SHOW_LOCUS:: Show location for runtime errors
601 * GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted
602 * GFORTRAN_DEFAULT_RECL:: Default record length for new files
603 * GFORTRAN_LIST_SEPARATOR:: Separator for list output
604 * GFORTRAN_CONVERT_UNIT:: Set endianness for unformatted I/O
605 * GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors
609 @section @env{TMPDIR}---Directory for scratch files
611 When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to
612 create the file in one of the potential directories by testing each
613 directory in the order below.
617 The environment variable @env{TMPDIR}, if it exists.
620 On the MinGW target, the directory returned by the @code{GetTempPath}
621 function. Alternatively, on the Cygwin target, the @env{TMP} and
622 @env{TEMP} environment variables, if they exist, in that order.
625 The @code{P_tmpdir} macro if it is defined, otherwise the directory
629 @node GFORTRAN_STDIN_UNIT
630 @section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input
632 This environment variable can be used to select the unit number
633 preconnected to standard input. This must be a positive integer.
634 The default value is 5.
636 @node GFORTRAN_STDOUT_UNIT
637 @section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output
639 This environment variable can be used to select the unit number
640 preconnected to standard output. This must be a positive integer.
641 The default value is 6.
643 @node GFORTRAN_STDERR_UNIT
644 @section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error
646 This environment variable can be used to select the unit number
647 preconnected to standard error. This must be a positive integer.
648 The default value is 0.
650 @node GFORTRAN_UNBUFFERED_ALL
651 @section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units
653 This environment variable controls whether all I/O is unbuffered. If
654 the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is
655 unbuffered. This will slow down small sequential reads and writes. If
656 the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered.
659 @node GFORTRAN_UNBUFFERED_PRECONNECTED
660 @section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units
662 The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls
663 whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) is unbuffered. If
664 the first letter is @samp{y}, @samp{Y} or @samp{1}, I/O is unbuffered. This
665 will slow down small sequential reads and writes. If the first letter
666 is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. This is the default.
668 @node GFORTRAN_SHOW_LOCUS
669 @section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors
671 If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and
672 line numbers for runtime errors are printed. If the first letter is
673 @samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers
674 for runtime errors. The default is to print the location.
676 @node GFORTRAN_OPTIONAL_PLUS
677 @section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted
679 If the first letter is @samp{y}, @samp{Y} or @samp{1},
680 a plus sign is printed
681 where permitted by the Fortran standard. If the first letter
682 is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed
683 in most cases. Default is not to print plus signs.
685 @node GFORTRAN_DEFAULT_RECL
686 @section @env{GFORTRAN_DEFAULT_RECL}---Default record length for new files
688 This environment variable specifies the default record length, in
689 bytes, for files which are opened without a @code{RECL} tag in the
690 @code{OPEN} statement. This must be a positive integer. The
691 default value is 1073741824 bytes (1 GB).
693 @node GFORTRAN_LIST_SEPARATOR
694 @section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output
696 This environment variable specifies the separator when writing
697 list-directed output. It may contain any number of spaces and
698 at most one comma. If you specify this on the command line,
699 be sure to quote spaces, as in
701 $ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out
703 when @command{a.out} is the compiled Fortran program that you want to run.
704 Default is a single space.
706 @node GFORTRAN_CONVERT_UNIT
707 @section @env{GFORTRAN_CONVERT_UNIT}---Set endianness for unformatted I/O
709 By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible
710 to change the representation of data for unformatted files.
711 The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable is:
713 GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ;
714 mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ;
715 exception: mode ':' unit_list | unit_list ;
716 unit_list: unit_spec | unit_list unit_spec ;
717 unit_spec: INTEGER | INTEGER '-' INTEGER ;
719 The variable consists of an optional default mode, followed by
720 a list of optional exceptions, which are separated by semicolons
721 from the preceding default and each other. Each exception consists
722 of a format and a comma-separated list of units. Valid values for
723 the modes are the same as for the @code{CONVERT} specifier:
726 @item @code{NATIVE} Use the native format. This is the default.
727 @item @code{SWAP} Swap between little- and big-endian.
728 @item @code{LITTLE_ENDIAN} Use the little-endian format
729 for unformatted files.
730 @item @code{BIG_ENDIAN} Use the big-endian format for unformatted files.
732 A missing mode for an exception is taken to mean @code{BIG_ENDIAN}.
733 Examples of values for @env{GFORTRAN_CONVERT_UNIT} are:
735 @item @code{'big_endian'} Do all unformatted I/O in big_endian mode.
736 @item @code{'little_endian;native:10-20,25'} Do all unformatted I/O
737 in little_endian mode, except for units 10 to 20 and 25, which are in
739 @item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native.
742 Setting the environment variables should be done on the command
743 line or via the @command{export}
744 command for @command{sh}-compatible shells and via @command{setenv}
745 for @command{csh}-compatible shells.
747 Example for @command{sh}:
750 $ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out
753 Example code for @command{csh}:
756 % setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20'
760 Using anything but the native representation for unformatted data
761 carries a significant speed overhead. If speed in this area matters
762 to you, it is best if you use this only for data that needs to be
765 @xref{CONVERT specifier}, for an alternative way to specify the
766 data representation for unformatted files. @xref{Runtime Options}, for
767 setting a default data representation for the whole program. The
768 @code{CONVERT} specifier overrides the @option{-fconvert} compile options.
770 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
771 environment variable will override the CONVERT specifier in the
772 open statement}. This is to give control over data formats to
773 users who do not have the source code of their program available.
775 @node GFORTRAN_ERROR_BACKTRACE
776 @section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors
778 If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to @samp{y},
779 @samp{Y} or @samp{1} (only the first letter is relevant) then a
780 backtrace is printed when a serious run-time error occurs. To disable
781 the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}.
782 Default is to print a backtrace unless the @option{-fno-backtrace}
783 compile option was used.
785 @c =====================================================================
786 @c PART II: LANGUAGE REFERENCE
787 @c =====================================================================
790 \part{II}{Language Reference}
793 @c ---------------------------------------------------------------------
794 @c Fortran 2003 and 2008 Status
795 @c ---------------------------------------------------------------------
797 @node Fortran 2003 and 2008 status
798 @chapter Fortran 2003 and 2008 Status
801 * Fortran 2003 status::
802 * Fortran 2008 status::
807 @node Fortran 2003 status
808 @section Fortran 2003 status
810 GNU Fortran supports several Fortran 2003 features; an incomplete
811 list can be found below. See also the
812 @uref{https://gcc.gnu.org/wiki/Fortran2003, wiki page} about Fortran 2003.
815 @item Procedure pointers including procedure-pointer components with
816 @code{PASS} attribute.
818 @item Procedures which are bound to a derived type (type-bound procedures)
819 including @code{PASS}, @code{PROCEDURE} and @code{GENERIC}, and
820 operators bound to a type.
822 @item Abstract interfaces and type extension with the possibility to
823 override type-bound procedures or to have deferred binding.
825 @item Polymorphic entities (``@code{CLASS}'') for derived types and unlimited
826 polymorphism (``@code{CLASS(*)}'') -- including @code{SAME_TYPE_AS},
827 @code{EXTENDS_TYPE_OF} and @code{SELECT TYPE} for scalars and arrays and
830 @item Generic interface names, which have the same name as derived types,
831 are now supported. This allows one to write constructor functions. Note
832 that Fortran does not support static constructor functions. For static
833 variables, only default initialization or structure-constructor
834 initialization are available.
836 @item The @code{ASSOCIATE} construct.
838 @item Interoperability with C including enumerations,
840 @item In structure constructors the components with default values may be
843 @item Extensions to the @code{ALLOCATE} statement, allowing for a
844 type-specification with type parameter and for allocation and initialization
845 from a @code{SOURCE=} expression; @code{ALLOCATE} and @code{DEALLOCATE}
846 optionally return an error message string via @code{ERRMSG=}.
848 @item Reallocation on assignment: If an intrinsic assignment is
849 used, an allocatable variable on the left-hand side is automatically allocated
850 (if unallocated) or reallocated (if the shape is different). Currently, scalar
851 deferred character length left-hand sides are correctly handled but arrays
852 are not yet fully implemented.
854 @item Deferred-length character variables and scalar deferred-length character
855 components of derived types are supported. (Note that array-valued compoents
856 are not yet implemented.)
858 @item Transferring of allocations via @code{MOVE_ALLOC}.
860 @item The @code{PRIVATE} and @code{PUBLIC} attributes may be given individually
861 to derived-type components.
863 @item In pointer assignments, the lower bound may be specified and
864 the remapping of elements is supported.
866 @item For pointers an @code{INTENT} may be specified which affect the
867 association status not the value of the pointer target.
869 @item Intrinsics @code{command_argument_count}, @code{get_command},
870 @code{get_command_argument}, and @code{get_environment_variable}.
872 @item Support for Unicode characters (ISO 10646) and UTF-8, including
873 the @code{SELECTED_CHAR_KIND} and @code{NEW_LINE} intrinsic functions.
875 @item Support for binary, octal and hexadecimal (BOZ) constants in the
876 intrinsic functions @code{INT}, @code{REAL}, @code{CMPLX} and @code{DBLE}.
878 @item Support for namelist variables with allocatable and pointer
879 attribute and nonconstant length type parameter.
882 @cindex array, constructors
884 Array constructors using square brackets. That is, @code{[...]} rather
885 than @code{(/.../)}. Type-specification for array constructors like
886 @code{(/ some-type :: ... /)}.
888 @item Extensions to the specification and initialization expressions,
889 including the support for intrinsics with real and complex arguments.
891 @item Support for the asynchronous input/output syntax; however, the
892 data transfer is currently always synchronously performed.
895 @cindex @code{FLUSH} statement
896 @cindex statement, @code{FLUSH}
897 @code{FLUSH} statement.
900 @cindex @code{IOMSG=} specifier
901 @code{IOMSG=} specifier for I/O statements.
904 @cindex @code{ENUM} statement
905 @cindex @code{ENUMERATOR} statement
906 @cindex statement, @code{ENUM}
907 @cindex statement, @code{ENUMERATOR}
908 @opindex @code{fshort-enums}
909 Support for the declaration of enumeration constants via the
910 @code{ENUM} and @code{ENUMERATOR} statements. Interoperability with
911 @command{gcc} is guaranteed also for the case where the
912 @command{-fshort-enums} command line option is given.
919 @cindex @code{ALLOCATABLE} dummy arguments
920 @code{ALLOCATABLE} dummy arguments.
922 @cindex @code{ALLOCATABLE} function results
923 @code{ALLOCATABLE} function results
925 @cindex @code{ALLOCATABLE} components of derived types
926 @code{ALLOCATABLE} components of derived types
930 @cindex @code{STREAM} I/O
931 @cindex @code{ACCESS='STREAM'} I/O
932 The @code{OPEN} statement supports the @code{ACCESS='STREAM'} specifier,
933 allowing I/O without any record structure.
936 Namelist input/output for internal files.
938 @item Minor I/O features: Rounding during formatted output, using of
939 a decimal comma instead of a decimal point, setting whether a plus sign
940 should appear for positive numbers. On systems where @code{strtod} honours
941 the rounding mode, the rounding mode is also supported for input.
944 @cindex @code{PROTECTED} statement
945 @cindex statement, @code{PROTECTED}
946 The @code{PROTECTED} statement and attribute.
949 @cindex @code{VALUE} statement
950 @cindex statement, @code{VALUE}
951 The @code{VALUE} statement and attribute.
954 @cindex @code{VOLATILE} statement
955 @cindex statement, @code{VOLATILE}
956 The @code{VOLATILE} statement and attribute.
959 @cindex @code{IMPORT} statement
960 @cindex statement, @code{IMPORT}
961 The @code{IMPORT} statement, allowing to import
962 host-associated derived types.
964 @item The intrinsic modules @code{ISO_FORTRAN_ENVIRONMENT} is supported,
965 which contains parameters of the I/O units, storage sizes. Additionally,
966 procedures for C interoperability are available in the @code{ISO_C_BINDING}
970 @cindex @code{USE, INTRINSIC} statement
971 @cindex statement, @code{USE, INTRINSIC}
972 @cindex @code{ISO_FORTRAN_ENV} statement
973 @cindex statement, @code{ISO_FORTRAN_ENV}
974 @code{USE} statement with @code{INTRINSIC} and @code{NON_INTRINSIC}
975 attribute; supported intrinsic modules: @code{ISO_FORTRAN_ENV},
976 @code{ISO_C_BINDING}, @code{OMP_LIB} and @code{OMP_LIB_KINDS},
980 Renaming of operators in the @code{USE} statement.
985 @node Fortran 2008 status
986 @section Fortran 2008 status
988 The latest version of the Fortran standard is ISO/IEC 1539-1:2010, informally
989 known as Fortran 2008. The official version is available from International
990 Organization for Standardization (ISO) or its national member organizations.
991 The the final draft (FDIS) can be downloaded free of charge from
992 @url{http://www.nag.co.uk/@/sc22wg5/@/links.html}. Fortran is developed by the
993 Working Group 5 of Sub-Committee 22 of the Joint Technical Committee 1 of the
994 International Organization for Standardization and the International
995 Electrotechnical Commission (IEC). This group is known as
996 @uref{http://www.nag.co.uk/sc22wg5/, WG5}.
998 The GNU Fortran compiler supports several of the new features of Fortran 2008;
999 the @uref{https://gcc.gnu.org/wiki/Fortran2008Status, wiki} has some information
1000 about the current Fortran 2008 implementation status. In particular, the
1001 following is implemented.
1004 @item The @option{-std=f2008} option and support for the file extensions
1005 @file{.f08} and @file{.F08}.
1007 @item The @code{OPEN} statement now supports the @code{NEWUNIT=} option,
1008 which returns a unique file unit, thus preventing inadvertent use of the
1009 same unit in different parts of the program.
1011 @item The @code{g0} format descriptor and unlimited format items.
1013 @item The mathematical intrinsics @code{ASINH}, @code{ACOSH}, @code{ATANH},
1014 @code{ERF}, @code{ERFC}, @code{GAMMA}, @code{LOG_GAMMA}, @code{BESSEL_J0},
1015 @code{BESSEL_J1}, @code{BESSEL_JN}, @code{BESSEL_Y0}, @code{BESSEL_Y1},
1016 @code{BESSEL_YN}, @code{HYPOT}, @code{NORM2}, and @code{ERFC_SCALED}.
1018 @item Using complex arguments with @code{TAN}, @code{SINH}, @code{COSH},
1019 @code{TANH}, @code{ASIN}, @code{ACOS}, and @code{ATAN} is now possible;
1020 @code{ATAN}(@var{Y},@var{X}) is now an alias for @code{ATAN2}(@var{Y},@var{X}).
1022 @item Support of the @code{PARITY} intrinsic functions.
1024 @item The following bit intrinsics: @code{LEADZ} and @code{TRAILZ} for
1025 counting the number of leading and trailing zero bits, @code{POPCNT} and
1026 @code{POPPAR} for counting the number of one bits and returning the parity;
1027 @code{BGE}, @code{BGT}, @code{BLE}, and @code{BLT} for bitwise comparisons;
1028 @code{DSHIFTL} and @code{DSHIFTR} for combined left and right shifts,
1029 @code{MASKL} and @code{MASKR} for simple left and right justified masks,
1030 @code{MERGE_BITS} for a bitwise merge using a mask, @code{SHIFTA},
1031 @code{SHIFTL} and @code{SHIFTR} for shift operations, and the
1032 transformational bit intrinsics @code{IALL}, @code{IANY} and @code{IPARITY}.
1034 @item Support of the @code{EXECUTE_COMMAND_LINE} intrinsic subroutine.
1036 @item Support for the @code{STORAGE_SIZE} intrinsic inquiry function.
1038 @item The @code{INT@{8,16,32@}} and @code{REAL@{32,64,128@}} kind type
1039 parameters and the array-valued named constants @code{INTEGER_KINDS},
1040 @code{LOGICAL_KINDS}, @code{REAL_KINDS} and @code{CHARACTER_KINDS} of
1041 the intrinsic module @code{ISO_FORTRAN_ENV}.
1043 @item The module procedures @code{C_SIZEOF} of the intrinsic module
1044 @code{ISO_C_BINDINGS} and @code{COMPILER_VERSION} and @code{COMPILER_OPTIONS}
1045 of @code{ISO_FORTRAN_ENV}.
1047 @item Coarray support for serial programs with @option{-fcoarray=single} flag
1048 and experimental support for multiple images with the @option{-fcoarray=lib}
1051 @item Submodules are supported. It should noted that @code{MODULEs} do not
1052 produce the smod file needed by the descendent @code{SUBMODULEs} unless they
1053 contain at least one @code{MODULE PROCEDURE} interface. The reason for this is
1054 that @code{SUBMODULEs} are useless without @code{MODULE PROCEDUREs}. See
1055 http://j3-fortran.org/doc/meeting/207/15-209.txt for a discussion and a draft
1056 interpretation. Adopting this interpretation has the advantage that code that
1057 does not use submodules does not generate smod files.
1059 @item The @code{DO CONCURRENT} construct is supported.
1061 @item The @code{BLOCK} construct is supported.
1063 @item The @code{STOP} and the new @code{ERROR STOP} statements now
1064 support all constant expressions. Both show the signals which were signaling
1067 @item Support for the @code{CONTIGUOUS} attribute.
1069 @item Support for @code{ALLOCATE} with @code{MOLD}.
1071 @item Support for the @code{IMPURE} attribute for procedures, which
1072 allows for @code{ELEMENTAL} procedures without the restrictions of
1075 @item Null pointers (including @code{NULL()}) and not-allocated variables
1076 can be used as actual argument to optional non-pointer, non-allocatable
1077 dummy arguments, denoting an absent argument.
1079 @item Non-pointer variables with @code{TARGET} attribute can be used as
1080 actual argument to @code{POINTER} dummies with @code{INTENT(IN)}.
1082 @item Pointers including procedure pointers and those in a derived
1083 type (pointer components) can now be initialized by a target instead
1084 of only by @code{NULL}.
1086 @item The @code{EXIT} statement (with construct-name) can be now be
1087 used to leave not only the @code{DO} but also the @code{ASSOCIATE},
1088 @code{BLOCK}, @code{IF}, @code{SELECT CASE} and @code{SELECT TYPE}
1091 @item Internal procedures can now be used as actual argument.
1093 @item Minor features: obsolesce diagnostics for @code{ENTRY} with
1094 @option{-std=f2008}; a line may start with a semicolon; for internal
1095 and module procedures @code{END} can be used instead of
1096 @code{END SUBROUTINE} and @code{END FUNCTION}; @code{SELECTED_REAL_KIND}
1097 now also takes a @code{RADIX} argument; intrinsic types are supported
1098 for @code{TYPE}(@var{intrinsic-type-spec}); multiple type-bound procedures
1099 can be declared in a single @code{PROCEDURE} statement; implied-shape
1100 arrays are supported for named constants (@code{PARAMETER}).
1105 @node TS 29113 status
1106 @section Technical Specification 29113 Status
1108 GNU Fortran supports some of the new features of the Technical
1109 Specification (TS) 29113 on Further Interoperability of Fortran with C.
1110 The @uref{https://gcc.gnu.org/wiki/TS29113Status, wiki} has some information
1111 about the current TS 29113 implementation status. In particular, the
1112 following is implemented.
1114 See also @ref{Further Interoperability of Fortran with C}.
1117 @item The @option{-std=f2008ts} option.
1119 @item The @code{OPTIONAL} attribute is allowed for dummy arguments
1120 of @code{BIND(C) procedures.}
1122 @item The @code{RANK} intrinsic is supported.
1124 @item GNU Fortran's implementation for variables with @code{ASYNCHRONOUS}
1125 attribute is compatible with TS 29113.
1127 @item Assumed types (@code{TYPE(*)}.
1129 @item Assumed-rank (@code{DIMENSION(..)}). However, the array descriptor
1130 of the TS is not yet supported.
1134 @node TS 18508 status
1135 @section Technical Specification 18508 Status
1137 GNU Fortran supports the following new features of the Technical
1138 Specification 18508 on Additional Parallel Features in Fortran:
1141 @item The new atomic ADD, CAS, FETCH and ADD/OR/XOR, OR and XOR intrinsics.
1143 @item The @code{CO_MIN} and @code{CO_MAX} and @code{SUM} reduction intrinsics.
1144 And the @code{CO_BROADCAST} and @code{CO_REDUCE} intrinsic, except that those
1145 do not support polymorphic types or types with allocatable, pointer or
1146 polymorphic components.
1148 @item Events (@code{EVENT POST}, @code{EVENT WAIT}, @code{EVENT_QUERY})
1152 @c ---------------------------------------------------------------------
1153 @c Compiler Characteristics
1154 @c ---------------------------------------------------------------------
1156 @node Compiler Characteristics
1157 @chapter Compiler Characteristics
1159 This chapter describes certain characteristics of the GNU Fortran
1160 compiler, that are not specified by the Fortran standard, but which
1161 might in some way or another become visible to the programmer.
1164 * KIND Type Parameters::
1165 * Internal representation of LOGICAL variables::
1166 * Thread-safety of the runtime library::
1167 * Data consistency and durability::
1168 * Files opened without an explicit ACTION= specifier::
1169 * File operations on symbolic links::
1173 @node KIND Type Parameters
1174 @section KIND Type Parameters
1177 The @code{KIND} type parameters supported by GNU Fortran for the primitive
1183 1, 2, 4, 8*, 16*, default: 4**
1186 1, 2, 4, 8*, 16*, default: 4**
1189 4, 8, 10*, 16*, default: 4***
1192 4, 8, 10*, 16*, default: 4***
1194 @item DOUBLE PRECISION
1195 4, 8, 10*, 16*, default: 8***
1203 * not available on all systems @*
1204 ** unless @option{-fdefault-integer-8} is used @*
1205 *** unless @option{-fdefault-real-8} is used (see @ref{Fortran Dialect Options})
1208 The @code{KIND} value matches the storage size in bytes, except for
1209 @code{COMPLEX} where the storage size is twice as much (or both real and
1210 imaginary part are a real value of the given size). It is recommended to use
1211 the @ref{SELECTED_CHAR_KIND}, @ref{SELECTED_INT_KIND} and
1212 @ref{SELECTED_REAL_KIND} intrinsics or the @code{INT8}, @code{INT16},
1213 @code{INT32}, @code{INT64}, @code{REAL32}, @code{REAL64}, and @code{REAL128}
1214 parameters of the @code{ISO_FORTRAN_ENV} module instead of the concrete values.
1215 The available kind parameters can be found in the constant arrays
1216 @code{CHARACTER_KINDS}, @code{INTEGER_KINDS}, @code{LOGICAL_KINDS} and
1217 @code{REAL_KINDS} in the @ref{ISO_FORTRAN_ENV} module. For C interoperability,
1218 the kind parameters of the @ref{ISO_C_BINDING} module should be used.
1221 @node Internal representation of LOGICAL variables
1222 @section Internal representation of LOGICAL variables
1223 @cindex logical, variable representation
1225 The Fortran standard does not specify how variables of @code{LOGICAL}
1226 type are represented, beyond requiring that @code{LOGICAL} variables
1227 of default kind have the same storage size as default @code{INTEGER}
1228 and @code{REAL} variables. The GNU Fortran internal representation is
1231 A @code{LOGICAL(KIND=N)} variable is represented as an
1232 @code{INTEGER(KIND=N)} variable, however, with only two permissible
1233 values: @code{1} for @code{.TRUE.} and @code{0} for
1234 @code{.FALSE.}. Any other integer value results in undefined behavior.
1236 See also @ref{Argument passing conventions} and @ref{Interoperability with C}.
1239 @node Thread-safety of the runtime library
1240 @section Thread-safety of the runtime library
1241 @cindex thread-safety, threads
1243 GNU Fortran can be used in programs with multiple threads, e.g.@: by
1244 using OpenMP, by calling OS thread handling functions via the
1245 @code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code
1246 being called from a multi-threaded program.
1248 The GNU Fortran runtime library, (@code{libgfortran}), supports being
1249 called concurrently from multiple threads with the following
1252 During library initialization, the C @code{getenv} function is used,
1253 which need not be thread-safe. Similarly, the @code{getenv}
1254 function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and
1255 @code{GETENV} intrinsics. It is the responsibility of the user to
1256 ensure that the environment is not being updated concurrently when any
1257 of these actions are taking place.
1259 The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are
1260 implemented with the @code{system} function, which need not be
1261 thread-safe. It is the responsibility of the user to ensure that
1262 @code{system} is not called concurrently.
1264 For platforms not supporting thread-safe POSIX functions, further
1265 functionality might not be thread-safe. For details, please consult
1266 the documentation for your operating system.
1268 The GNU Fortran runtime library uses various C library functions that
1269 depend on the locale, such as @code{strtod} and @code{snprintf}. In
1270 order to work correctly in locale-aware programs that set the locale
1271 using @code{setlocale}, the locale is reset to the default ``C''
1272 locale while executing a formatted @code{READ} or @code{WRITE}
1273 statement. On targets supporting the POSIX 2008 per-thread locale
1274 functions (e.g. @code{newlocale}, @code{uselocale},
1275 @code{freelocale}), these are used and thus the global locale set
1276 using @code{setlocale} or the per-thread locales in other threads are
1277 not affected. However, on targets lacking this functionality, the
1278 global LC_NUMERIC locale is set to ``C'' during the formatted I/O.
1279 Thus, on such targets it's not safe to call @code{setlocale}
1280 concurrently from another thread while a Fortran formatted I/O
1281 operation is in progress. Also, other threads doing something
1282 dependent on the LC_NUMERIC locale might not work correctly if a
1283 formatted I/O operation is in progress in another thread.
1285 @node Data consistency and durability
1286 @section Data consistency and durability
1287 @cindex consistency, durability
1289 This section contains a brief overview of data and metadata
1290 consistency and durability issues when doing I/O.
1292 With respect to durability, GNU Fortran makes no effort to ensure that
1293 data is committed to stable storage. If this is required, the GNU
1294 Fortran programmer can use the intrinsic @code{FNUM} to retrieve the
1295 low level file descriptor corresponding to an open Fortran unit. Then,
1296 using e.g. the @code{ISO_C_BINDING} feature, one can call the
1297 underlying system call to flush dirty data to stable storage, such as
1298 @code{fsync} on POSIX, @code{_commit} on MingW, or @code{fcntl(fd,
1299 F_FULLSYNC, 0)} on Mac OS X. The following example shows how to call
1303 ! Declare the interface for POSIX fsync function
1305 function fsync (fd) bind(c,name="fsync")
1306 use iso_c_binding, only: c_int
1307 integer(c_int), value :: fd
1308 integer(c_int) :: fsync
1312 ! Variable declaration
1316 open (10,file="foo")
1319 ! Perform I/O on unit 10
1324 ret = fsync(fnum(10))
1326 ! Handle possible error
1327 if (ret /= 0) stop "Error calling FSYNC"
1330 With respect to consistency, for regular files GNU Fortran uses
1331 buffered I/O in order to improve performance. This buffer is flushed
1332 automatically when full and in some other situations, e.g. when
1333 closing a unit. It can also be explicitly flushed with the
1334 @code{FLUSH} statement. Also, the buffering can be turned off with the
1335 @code{GFORTRAN_UNBUFFERED_ALL} and
1336 @code{GFORTRAN_UNBUFFERED_PRECONNECTED} environment variables. Special
1337 files, such as terminals and pipes, are always unbuffered. Sometimes,
1338 however, further things may need to be done in order to allow other
1339 processes to see data that GNU Fortran has written, as follows.
1341 The Windows platform supports a relaxed metadata consistency model,
1342 where file metadata is written to the directory lazily. This means
1343 that, for instance, the @code{dir} command can show a stale size for a
1344 file. One can force a directory metadata update by closing the unit,
1345 or by calling @code{_commit} on the file descriptor. Note, though,
1346 that @code{_commit} will force all dirty data to stable storage, which
1347 is often a very slow operation.
1349 The Network File System (NFS) implements a relaxed consistency model
1350 called open-to-close consistency. Closing a file forces dirty data and
1351 metadata to be flushed to the server, and opening a file forces the
1352 client to contact the server in order to revalidate cached
1353 data. @code{fsync} will also force a flush of dirty data and metadata
1354 to the server. Similar to @code{open} and @code{close}, acquiring and
1355 releasing @code{fcntl} file locks, if the server supports them, will
1356 also force cache validation and flushing dirty data and metadata.
1359 @node Files opened without an explicit ACTION= specifier
1360 @section Files opened without an explicit ACTION= specifier
1361 @cindex open, action
1363 The Fortran standard says that if an @code{OPEN} statement is executed
1364 without an explicit @code{ACTION=} specifier, the default value is
1365 processor dependent. GNU Fortran behaves as follows:
1368 @item Attempt to open the file with @code{ACTION='READWRITE'}
1369 @item If that fails, try to open with @code{ACTION='READ'}
1370 @item If that fails, try to open with @code{ACTION='WRITE'}
1371 @item If that fails, generate an error
1375 @node File operations on symbolic links
1376 @section File operations on symbolic links
1377 @cindex file, symbolic link
1379 This section documents the behavior of GNU Fortran for file operations on
1380 symbolic links, on systems that support them.
1384 @item Results of INQUIRE statements of the ``inquire by file'' form will
1385 relate to the target of the symbolic link. For example,
1386 @code{INQUIRE(FILE="foo",EXIST=ex)} will set @var{ex} to @var{.true.} if
1387 @var{foo} is a symbolic link pointing to an existing file, and @var{.false.}
1388 if @var{foo} points to an non-existing file (``dangling'' symbolic link).
1390 @item Using the @code{OPEN} statement with a @code{STATUS="NEW"} specifier
1391 on a symbolic link will result in an error condition, whether the symbolic
1392 link points to an existing target or is dangling.
1394 @item If a symbolic link was connected, using the @code{CLOSE} statement
1395 with a @code{STATUS="DELETE"} specifier will cause the symbolic link itself
1396 to be deleted, not its target.
1402 @c ---------------------------------------------------------------------
1404 @c ---------------------------------------------------------------------
1406 @c Maybe this chapter should be merged with the 'Standards' section,
1407 @c whenever that is written :-)
1413 The two sections below detail the extensions to standard Fortran that are
1414 implemented in GNU Fortran, as well as some of the popular or
1415 historically important extensions that are not (or not yet) implemented.
1416 For the latter case, we explain the alternatives available to GNU Fortran
1417 users, including replacement by standard-conforming code or GNU
1421 * Extensions implemented in GNU Fortran::
1422 * Extensions not implemented in GNU Fortran::
1426 @node Extensions implemented in GNU Fortran
1427 @section Extensions implemented in GNU Fortran
1428 @cindex extensions, implemented
1430 GNU Fortran implements a number of extensions over standard
1431 Fortran. This chapter contains information on their syntax and
1432 meaning. There are currently two categories of GNU Fortran
1433 extensions, those that provide functionality beyond that provided
1434 by any standard, and those that are supported by GNU Fortran
1435 purely for backward compatibility with legacy compilers. By default,
1436 @option{-std=gnu} allows the compiler to accept both types of
1437 extensions, but to warn about the use of the latter. Specifying
1438 either @option{-std=f95}, @option{-std=f2003} or @option{-std=f2008}
1439 disables both types of extensions, and @option{-std=legacy} allows both
1443 * Old-style kind specifications::
1444 * Old-style variable initialization::
1445 * Extensions to namelist::
1446 * X format descriptor without count field::
1447 * Commas in FORMAT specifications::
1448 * Missing period in FORMAT specifications::
1450 * @code{Q} exponent-letter::
1451 * BOZ literal constants::
1452 * Real array indices::
1454 * Implicitly convert LOGICAL and INTEGER values::
1455 * Hollerith constants support::
1457 * CONVERT specifier::
1460 * Argument list functions::
1461 * Read/Write after EOF marker::
1464 @node Old-style kind specifications
1465 @subsection Old-style kind specifications
1466 @cindex kind, old-style
1468 GNU Fortran allows old-style kind specifications in declarations. These
1474 where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
1475 etc.), and where @code{size} is a byte count corresponding to the
1476 storage size of a valid kind for that type. (For @code{COMPLEX}
1477 variables, @code{size} is the total size of the real and imaginary
1478 parts.) The statement then declares @code{x}, @code{y} and @code{z} to
1479 be of type @code{TYPESPEC} with the appropriate kind. This is
1480 equivalent to the standard-conforming declaration
1485 where @code{k} is the kind parameter suitable for the intended precision. As
1486 kind parameters are implementation-dependent, use the @code{KIND},
1487 @code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve
1488 the correct value, for instance @code{REAL*8 x} can be replaced by:
1490 INTEGER, PARAMETER :: dbl = KIND(1.0d0)
1494 @node Old-style variable initialization
1495 @subsection Old-style variable initialization
1497 GNU Fortran allows old-style initialization of variables of the
1501 REAL x(2,2) /3*0.,1./
1503 The syntax for the initializers is as for the @code{DATA} statement, but
1504 unlike in a @code{DATA} statement, an initializer only applies to the
1505 variable immediately preceding the initialization. In other words,
1506 something like @code{INTEGER I,J/2,3/} is not valid. This style of
1507 initialization is only allowed in declarations without double colons
1508 (@code{::}); the double colons were introduced in Fortran 90, which also
1509 introduced a standard syntax for initializing variables in type
1512 Examples of standard-conforming code equivalent to the above example
1516 INTEGER :: i = 1, j = 2
1517 REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
1521 DATA i/1/, j/2/, x/3*0.,1./
1524 Note that variables which are explicitly initialized in declarations
1525 or in @code{DATA} statements automatically acquire the @code{SAVE}
1528 @node Extensions to namelist
1529 @subsection Extensions to namelist
1532 GNU Fortran fully supports the Fortran 95 standard for namelist I/O
1533 including array qualifiers, substrings and fully qualified derived types.
1534 The output from a namelist write is compatible with namelist read. The
1535 output has all names in upper case and indentation to column 1 after the
1536 namelist name. Two extensions are permitted:
1538 Old-style use of @samp{$} instead of @samp{&}
1541 X(:)%Y(2) = 1.0 2.0 3.0
1546 It should be noted that the default terminator is @samp{/} rather than
1549 Querying of the namelist when inputting from stdin. After at least
1550 one space, entering @samp{?} sends to stdout the namelist name and the names of
1551 the variables in the namelist:
1562 Entering @samp{=?} outputs the namelist to stdout, as if
1563 @code{WRITE(*,NML = mynml)} had been called:
1568 X(1)%Y= 0.000000 , 1.000000 , 0.000000 ,
1569 X(2)%Y= 0.000000 , 2.000000 , 0.000000 ,
1570 X(3)%Y= 0.000000 , 3.000000 , 0.000000 ,
1574 To aid this dialog, when input is from stdin, errors send their
1575 messages to stderr and execution continues, even if @code{IOSTAT} is set.
1577 @code{PRINT} namelist is permitted. This causes an error if
1578 @option{-std=f95} is used.
1581 REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/)
1584 END PROGRAM test_print
1587 Expanded namelist reads are permitted. This causes an error if
1588 @option{-std=f95} is used. In the following example, the first element
1589 of the array will be given the value 0.00 and the two succeeding
1590 elements will be given the values 1.00 and 2.00.
1593 X(1,1) = 0.00 , 1.00 , 2.00
1597 When writing a namelist, if no @code{DELIM=} is specified, by default a
1598 double quote is used to delimit character strings. If -std=F95, F2003,
1599 or F2008, etc, the delim status is set to 'none'. Defaulting to
1600 quotes ensures that namelists with character strings can be subsequently
1601 read back in accurately.
1603 @node X format descriptor without count field
1604 @subsection @code{X} format descriptor without count field
1606 To support legacy codes, GNU Fortran permits the count field of the
1607 @code{X} edit descriptor in @code{FORMAT} statements to be omitted.
1608 When omitted, the count is implicitly assumed to be one.
1612 10 FORMAT (I1, X, I1)
1615 @node Commas in FORMAT specifications
1616 @subsection Commas in @code{FORMAT} specifications
1618 To support legacy codes, GNU Fortran allows the comma separator
1619 to be omitted immediately before and after character string edit
1620 descriptors in @code{FORMAT} statements.
1624 10 FORMAT ('FOO='I1' BAR='I2)
1628 @node Missing period in FORMAT specifications
1629 @subsection Missing period in @code{FORMAT} specifications
1631 To support legacy codes, GNU Fortran allows missing periods in format
1632 specifications if and only if @option{-std=legacy} is given on the
1633 command line. This is considered non-conforming code and is
1642 @node I/O item lists
1643 @subsection I/O item lists
1644 @cindex I/O item lists
1646 To support legacy codes, GNU Fortran allows the input item list
1647 of the @code{READ} statement, and the output item lists of the
1648 @code{WRITE} and @code{PRINT} statements, to start with a comma.
1650 @node @code{Q} exponent-letter
1651 @subsection @code{Q} exponent-letter
1652 @cindex @code{Q} exponent-letter
1654 GNU Fortran accepts real literal constants with an exponent-letter
1655 of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted
1656 as a @code{REAL(16)} entity on targets that support this type. If
1657 the target does not support @code{REAL(16)} but has a @code{REAL(10)}
1658 type, then the real-literal-constant will be interpreted as a
1659 @code{REAL(10)} entity. In the absence of @code{REAL(16)} and
1660 @code{REAL(10)}, an error will occur.
1662 @node BOZ literal constants
1663 @subsection BOZ literal constants
1664 @cindex BOZ literal constants
1666 Besides decimal constants, Fortran also supports binary (@code{b}),
1667 octal (@code{o}) and hexadecimal (@code{z}) integer constants. The
1668 syntax is: @samp{prefix quote digits quote}, were the prefix is
1669 either @code{b}, @code{o} or @code{z}, quote is either @code{'} or
1670 @code{"} and the digits are for binary @code{0} or @code{1}, for
1671 octal between @code{0} and @code{7}, and for hexadecimal between
1672 @code{0} and @code{F}. (Example: @code{b'01011101'}.)
1674 Up to Fortran 95, BOZ literals were only allowed to initialize
1675 integer variables in DATA statements. Since Fortran 2003 BOZ literals
1676 are also allowed as argument of @code{REAL}, @code{DBLE}, @code{INT}
1677 and @code{CMPLX}; the result is the same as if the integer BOZ
1678 literal had been converted by @code{TRANSFER} to, respectively,
1679 @code{real}, @code{double precision}, @code{integer} or @code{complex}.
1680 As GNU Fortran extension the intrinsic procedures @code{FLOAT},
1681 @code{DFLOAT}, @code{COMPLEX} and @code{DCMPLX} are treated alike.
1683 As an extension, GNU Fortran allows hexadecimal BOZ literal constants to
1684 be specified using the @code{X} prefix, in addition to the standard
1685 @code{Z} prefix. The BOZ literal can also be specified by adding a
1686 suffix to the string, for example, @code{Z'ABC'} and @code{'ABC'Z} are
1689 Furthermore, GNU Fortran allows using BOZ literal constants outside
1690 DATA statements and the four intrinsic functions allowed by Fortran 2003.
1691 In DATA statements, in direct assignments, where the right-hand side
1692 only contains a BOZ literal constant, and for old-style initializers of
1693 the form @code{integer i /o'0173'/}, the constant is transferred
1694 as if @code{TRANSFER} had been used; for @code{COMPLEX} numbers, only
1695 the real part is initialized unless @code{CMPLX} is used. In all other
1696 cases, the BOZ literal constant is converted to an @code{INTEGER} value with
1697 the largest decimal representation. This value is then converted
1698 numerically to the type and kind of the variable in question.
1699 (For instance, @code{real :: r = b'0000001' + 1} initializes @code{r}
1700 with @code{2.0}.) As different compilers implement the extension
1701 differently, one should be careful when doing bitwise initialization
1702 of non-integer variables.
1704 Note that initializing an @code{INTEGER} variable with a statement such
1705 as @code{DATA i/Z'FFFFFFFF'/} will give an integer overflow error rather
1706 than the desired result of @math{-1} when @code{i} is a 32-bit integer
1707 on a system that supports 64-bit integers. The @samp{-fno-range-check}
1708 option can be used as a workaround for legacy code that initializes
1709 integers in this manner.
1711 @node Real array indices
1712 @subsection Real array indices
1713 @cindex array, indices of type real
1715 As an extension, GNU Fortran allows the use of @code{REAL} expressions
1716 or variables as array indices.
1718 @node Unary operators
1719 @subsection Unary operators
1720 @cindex operators, unary
1722 As an extension, GNU Fortran allows unary plus and unary minus operators
1723 to appear as the second operand of binary arithmetic operators without
1724 the need for parenthesis.
1730 @node Implicitly convert LOGICAL and INTEGER values
1731 @subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values
1732 @cindex conversion, to integer
1733 @cindex conversion, to logical
1735 As an extension for backwards compatibility with other compilers, GNU
1736 Fortran allows the implicit conversion of @code{LOGICAL} values to
1737 @code{INTEGER} values and vice versa. When converting from a
1738 @code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as
1739 zero, and @code{.TRUE.} is interpreted as one. When converting from
1740 @code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as
1741 @code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}.
1752 However, there is no implicit conversion of @code{INTEGER} values in
1753 @code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values
1756 @node Hollerith constants support
1757 @subsection Hollerith constants support
1758 @cindex Hollerith constants
1760 GNU Fortran supports Hollerith constants in assignments, function
1761 arguments, and @code{DATA} and @code{ASSIGN} statements. A Hollerith
1762 constant is written as a string of characters preceded by an integer
1763 constant indicating the character count, and the letter @code{H} or
1764 @code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER},
1765 @code{REAL}, or @code{complex}) or @code{LOGICAL} variable. The
1766 constant will be padded or truncated to fit the size of the variable in
1769 Examples of valid uses of Hollerith constants:
1772 data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/
1773 x(1) = 16HABCDEFGHIJKLMNOP
1777 Invalid Hollerith constants examples:
1780 a = 8H12345678 ! Valid, but the Hollerith constant will be truncated.
1781 a = 0H ! At least one character is needed.
1784 In general, Hollerith constants were used to provide a rudimentary
1785 facility for handling character strings in early Fortran compilers,
1786 prior to the introduction of @code{CHARACTER} variables in Fortran 77;
1787 in those cases, the standard-compliant equivalent is to convert the
1788 program to use proper character strings. On occasion, there may be a
1789 case where the intent is specifically to initialize a numeric variable
1790 with a given byte sequence. In these cases, the same result can be
1791 obtained by using the @code{TRANSFER} statement, as in this example.
1793 INTEGER(KIND=4) :: a
1794 a = TRANSFER ("abcd", a) ! equivalent to: a = 4Habcd
1799 @subsection Cray pointers
1800 @cindex pointer, Cray
1802 Cray pointers are part of a non-standard extension that provides a
1803 C-like pointer in Fortran. This is accomplished through a pair of
1804 variables: an integer "pointer" that holds a memory address, and a
1805 "pointee" that is used to dereference the pointer.
1807 Pointer/pointee pairs are declared in statements of the form:
1809 pointer ( <pointer> , <pointee> )
1813 pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ...
1815 The pointer is an integer that is intended to hold a memory address.
1816 The pointee may be an array or scalar. A pointee can be an assumed
1817 size array---that is, the last dimension may be left unspecified by
1818 using a @code{*} in place of a value---but a pointee cannot be an
1819 assumed shape array. No space is allocated for the pointee.
1821 The pointee may have its type declared before or after the pointer
1822 statement, and its array specification (if any) may be declared
1823 before, during, or after the pointer statement. The pointer may be
1824 declared as an integer prior to the pointer statement. However, some
1825 machines have default integer sizes that are different than the size
1826 of a pointer, and so the following code is not portable:
1831 If a pointer is declared with a kind that is too small, the compiler
1832 will issue a warning; the resulting binary will probably not work
1833 correctly, because the memory addresses stored in the pointers may be
1834 truncated. It is safer to omit the first line of the above example;
1835 if explicit declaration of ipt's type is omitted, then the compiler
1836 will ensure that ipt is an integer variable large enough to hold a
1839 Pointer arithmetic is valid with Cray pointers, but it is not the same
1840 as C pointer arithmetic. Cray pointers are just ordinary integers, so
1841 the user is responsible for determining how many bytes to add to a
1842 pointer in order to increment it. Consider the following example:
1846 pointer (ipt, pointee)
1850 The last statement does not set @code{ipt} to the address of
1851 @code{target(1)}, as it would in C pointer arithmetic. Adding @code{1}
1852 to @code{ipt} just adds one byte to the address stored in @code{ipt}.
1854 Any expression involving the pointee will be translated to use the
1855 value stored in the pointer as the base address.
1857 To get the address of elements, this extension provides an intrinsic
1858 function @code{LOC()}. The @code{LOC()} function is equivalent to the
1859 @code{&} operator in C, except the address is cast to an integer type:
1862 pointer(ipt, arpte(10))
1864 ipt = loc(ar) ! Makes arpte is an alias for ar
1865 arpte(1) = 1.0 ! Sets ar(1) to 1.0
1867 The pointer can also be set by a call to the @code{MALLOC} intrinsic
1870 Cray pointees often are used to alias an existing variable. For
1878 As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for
1879 @code{target}. The optimizer, however, will not detect this aliasing, so
1880 it is unsafe to use @code{iarr} and @code{target} simultaneously. Using
1881 a pointee in any way that violates the Fortran aliasing rules or
1882 assumptions is illegal. It is the user's responsibility to avoid doing
1883 this; the compiler works under the assumption that no such aliasing
1886 Cray pointers will work correctly when there is no aliasing (i.e., when
1887 they are used to access a dynamically allocated block of memory), and
1888 also in any routine where a pointee is used, but any variable with which
1889 it shares storage is not used. Code that violates these rules may not
1890 run as the user intends. This is not a bug in the optimizer; any code
1891 that violates the aliasing rules is illegal. (Note that this is not
1892 unique to GNU Fortran; any Fortran compiler that supports Cray pointers
1893 will ``incorrectly'' optimize code with illegal aliasing.)
1895 There are a number of restrictions on the attributes that can be applied
1896 to Cray pointers and pointees. Pointees may not have the
1897 @code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY},
1898 @code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers
1899 may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET},
1900 @code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor
1901 may they be function results. Pointees may not occur in more than one
1902 pointer statement. A pointee cannot be a pointer. Pointees cannot occur
1903 in equivalence, common, or data statements.
1905 A Cray pointer may also point to a function or a subroutine. For
1906 example, the following excerpt is valid:
1910 pointer (subptr,subpte)
1920 A pointer may be modified during the course of a program, and this
1921 will change the location to which the pointee refers. However, when
1922 pointees are passed as arguments, they are treated as ordinary
1923 variables in the invoked function. Subsequent changes to the pointer
1924 will not change the base address of the array that was passed.
1926 @node CONVERT specifier
1927 @subsection @code{CONVERT} specifier
1928 @cindex @code{CONVERT} specifier
1930 GNU Fortran allows the conversion of unformatted data between little-
1931 and big-endian representation to facilitate moving of data
1932 between different systems. The conversion can be indicated with
1933 the @code{CONVERT} specifier on the @code{OPEN} statement.
1934 @xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying
1935 the data format via an environment variable.
1937 Valid values for @code{CONVERT} are:
1939 @item @code{CONVERT='NATIVE'} Use the native format. This is the default.
1940 @item @code{CONVERT='SWAP'} Swap between little- and big-endian.
1941 @item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation
1942 for unformatted files.
1943 @item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for
1947 Using the option could look like this:
1949 open(file='big.dat',form='unformatted',access='sequential', &
1950 convert='big_endian')
1953 The value of the conversion can be queried by using
1954 @code{INQUIRE(CONVERT=ch)}. The values returned are
1955 @code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}.
1957 @code{CONVERT} works between big- and little-endian for
1958 @code{INTEGER} values of all supported kinds and for @code{REAL}
1959 on IEEE systems of kinds 4 and 8. Conversion between different
1960 ``extended double'' types on different architectures such as
1961 m68k and x86_64, which GNU Fortran
1962 supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will
1965 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
1966 environment variable will override the CONVERT specifier in the
1967 open statement}. This is to give control over data formats to
1968 users who do not have the source code of their program available.
1970 Using anything but the native representation for unformatted data
1971 carries a significant speed overhead. If speed in this area matters
1972 to you, it is best if you use this only for data that needs to be
1979 OpenMP (Open Multi-Processing) is an application programming
1980 interface (API) that supports multi-platform shared memory
1981 multiprocessing programming in C/C++ and Fortran on many
1982 architectures, including Unix and Microsoft Windows platforms.
1983 It consists of a set of compiler directives, library routines,
1984 and environment variables that influence run-time behavior.
1986 GNU Fortran strives to be compatible to the
1987 @uref{http://openmp.org/wp/openmp-specifications/,
1988 OpenMP Application Program Interface v4.0}.
1990 To enable the processing of the OpenMP directive @code{!$omp} in
1991 free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp}
1992 directives in fixed form; the @code{!$} conditional compilation sentinels
1993 in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels
1994 in fixed form, @command{gfortran} needs to be invoked with the
1995 @option{-fopenmp}. This also arranges for automatic linking of the
1996 GNU Offloading and Multi Processing Runtime Library
1997 @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
2000 The OpenMP Fortran runtime library routines are provided both in a
2001 form of a Fortran 90 module named @code{omp_lib} and in a form of
2002 a Fortran @code{include} file named @file{omp_lib.h}.
2004 An example of a parallelized loop taken from Appendix A.1 of
2005 the OpenMP Application Program Interface v2.5:
2007 SUBROUTINE A1(N, A, B)
2010 !$OMP PARALLEL DO !I is private by default
2012 B(I) = (A(I) + A(I-1)) / 2.0
2014 !$OMP END PARALLEL DO
2021 @option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays
2022 will be allocated on the stack. When porting existing code to OpenMP,
2023 this may lead to surprising results, especially to segmentation faults
2024 if the stacksize is limited.
2027 On glibc-based systems, OpenMP enabled applications cannot be statically
2028 linked due to limitations of the underlying pthreads-implementation. It
2029 might be possible to get a working solution if
2030 @command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added
2031 to the command line. However, this is not supported by @command{gcc} and
2032 thus not recommended.
2039 OpenACC is an application programming interface (API) that supports
2040 offloading of code to accelerator devices. It consists of a set of
2041 compiler directives, library routines, and environment variables that
2042 influence run-time behavior.
2044 GNU Fortran strives to be compatible to the
2045 @uref{http://www.openacc.org/, OpenACC Application Programming
2048 To enable the processing of the OpenACC directive @code{!$acc} in
2049 free-form source code; the @code{c$acc}, @code{*$acc} and @code{!$acc}
2050 directives in fixed form; the @code{!$} conditional compilation
2051 sentinels in free form; and the @code{c$}, @code{*$} and @code{!$}
2052 sentinels in fixed form, @command{gfortran} needs to be invoked with
2053 the @option{-fopenacc}. This also arranges for automatic linking of
2054 the GNU Offloading and Multi Processing Runtime Library
2055 @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
2058 The OpenACC Fortran runtime library routines are provided both in a
2059 form of a Fortran 90 module named @code{openacc} and in a form of a
2060 Fortran @code{include} file named @file{openacc_lib.h}.
2062 Note that this is an experimental feature, incomplete, and subject to
2063 change in future versions of GCC. See
2064 @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
2066 @node Argument list functions
2067 @subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC}
2068 @cindex argument list functions
2073 GNU Fortran supports argument list functions @code{%VAL}, @code{%REF}
2074 and @code{%LOC} statements, for backward compatibility with g77.
2075 It is recommended that these should be used only for code that is
2076 accessing facilities outside of GNU Fortran, such as operating system
2077 or windowing facilities. It is best to constrain such uses to isolated
2078 portions of a program--portions that deal specifically and exclusively
2079 with low-level, system-dependent facilities. Such portions might well
2080 provide a portable interface for use by the program as a whole, but are
2081 themselves not portable, and should be thoroughly tested each time they
2082 are rebuilt using a new compiler or version of a compiler.
2084 @code{%VAL} passes a scalar argument by value, @code{%REF} passes it by
2085 reference and @code{%LOC} passes its memory location. Since gfortran
2086 already passes scalar arguments by reference, @code{%REF} is in effect
2087 a do-nothing. @code{%LOC} has the same effect as a Fortran pointer.
2089 An example of passing an argument by value to a C subroutine foo.:
2092 C prototype void foo_ (float x);
2101 For details refer to the g77 manual
2102 @uref{https://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}.
2104 Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the
2105 GNU Fortran testsuite are worth a look.
2107 @node Read/Write after EOF marker
2108 @subsection Read/Write after EOF marker
2110 @cindex @code{BACKSPACE}
2111 @cindex @code{REWIND}
2113 Some legacy codes rely on allowing @code{READ} or @code{WRITE} after the
2114 EOF file marker in order to find the end of a file. GNU Fortran normally
2115 rejects these codes with a run-time error message and suggests the user
2116 consider @code{BACKSPACE} or @code{REWIND} to properly position
2117 the file before the EOF marker. As an extension, the run-time error may
2118 be disabled using -std=legacy.
2120 @node Extensions not implemented in GNU Fortran
2121 @section Extensions not implemented in GNU Fortran
2122 @cindex extensions, not implemented
2124 The long history of the Fortran language, its wide use and broad
2125 userbase, the large number of different compiler vendors and the lack of
2126 some features crucial to users in the first standards have lead to the
2127 existence of a number of important extensions to the language. While
2128 some of the most useful or popular extensions are supported by the GNU
2129 Fortran compiler, not all existing extensions are supported. This section
2130 aims at listing these extensions and offering advice on how best make
2131 code that uses them running with the GNU Fortran compiler.
2133 @c More can be found here:
2134 @c -- https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html
2135 @c -- the list of Fortran and libgfortran bugs closed as WONTFIX:
2136 @c http://tinyurl.com/2u4h5y
2139 * STRUCTURE and RECORD::
2140 @c * UNION and MAP::
2141 * ENCODE and DECODE statements::
2142 * Variable FORMAT expressions::
2143 @c * Q edit descriptor::
2144 @c * AUTOMATIC statement::
2145 @c * TYPE and ACCEPT I/O Statements::
2146 @c * .XOR. operator::
2147 @c * CARRIAGECONTROL, DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers::
2148 @c * Omitted arguments in procedure call::
2149 * Alternate complex function syntax::
2150 * Volatile COMMON blocks::
2154 @node STRUCTURE and RECORD
2155 @subsection @code{STRUCTURE} and @code{RECORD}
2156 @cindex @code{STRUCTURE}
2157 @cindex @code{RECORD}
2159 Record structures are a pre-Fortran-90 vendor extension to create
2160 user-defined aggregate data types. GNU Fortran does not support
2161 record structures, only Fortran 90's ``derived types'', which have
2164 In many cases, record structures can easily be converted to derived types.
2165 To convert, replace @code{STRUCTURE /}@var{structure-name}@code{/}
2166 by @code{TYPE} @var{type-name}. Additionally, replace
2167 @code{RECORD /}@var{structure-name}@code{/} by
2168 @code{TYPE(}@var{type-name}@code{)}. Finally, in the component access,
2169 replace the period (@code{.}) by the percent sign (@code{%}).
2171 Here is an example of code using the non portable record structure syntax:
2174 ! Declaring a structure named ``item'' and containing three fields:
2175 ! an integer ID, an description string and a floating-point price.
2178 CHARACTER(LEN=200) description
2182 ! Define two variables, an single record of type ``item''
2183 ! named ``pear'', and an array of items named ``store_catalog''
2184 RECORD /item/ pear, store_catalog(100)
2186 ! We can directly access the fields of both variables
2188 pear.description = "juicy D'Anjou pear"
2190 store_catalog(7).id = 7831
2191 store_catalog(7).description = "milk bottle"
2192 store_catalog(7).price = 1.2
2194 ! We can also manipulate the whole structure
2195 store_catalog(12) = pear
2196 print *, store_catalog(12)
2200 This code can easily be rewritten in the Fortran 90 syntax as following:
2203 ! ``STRUCTURE /name/ ... END STRUCTURE'' becomes
2204 ! ``TYPE name ... END TYPE''
2207 CHARACTER(LEN=200) description
2211 ! ``RECORD /name/ variable'' becomes ``TYPE(name) variable''
2212 TYPE(item) pear, store_catalog(100)
2214 ! Instead of using a dot (.) to access fields of a record, the
2215 ! standard syntax uses a percent sign (%)
2217 pear%description = "juicy D'Anjou pear"
2219 store_catalog(7)%id = 7831
2220 store_catalog(7)%description = "milk bottle"
2221 store_catalog(7)%price = 1.2
2223 ! Assignments of a whole variable do not change
2224 store_catalog(12) = pear
2225 print *, store_catalog(12)
2229 @c @node UNION and MAP
2230 @c @subsection @code{UNION} and @code{MAP}
2231 @c @cindex @code{UNION}
2232 @c @cindex @code{MAP}
2234 @c For help writing this one, see
2235 @c http://www.eng.umd.edu/~nsw/ench250/fortran1.htm#UNION and
2236 @c http://www.tacc.utexas.edu/services/userguides/pgi/pgiws_ug/pgi32u06.htm
2239 @node ENCODE and DECODE statements
2240 @subsection @code{ENCODE} and @code{DECODE} statements
2241 @cindex @code{ENCODE}
2242 @cindex @code{DECODE}
2244 GNU Fortran does not support the @code{ENCODE} and @code{DECODE}
2245 statements. These statements are best replaced by @code{READ} and
2246 @code{WRITE} statements involving internal files (@code{CHARACTER}
2247 variables and arrays), which have been part of the Fortran standard since
2248 Fortran 77. For example, replace a code fragment like
2253 c ... Code that sets LINE
2254 DECODE (80, 9000, LINE) A, B, C
2255 9000 FORMAT (1X, 3(F10.5))
2262 CHARACTER(LEN=80) LINE
2264 c ... Code that sets LINE
2265 READ (UNIT=LINE, FMT=9000) A, B, C
2266 9000 FORMAT (1X, 3(F10.5))
2269 Similarly, replace a code fragment like
2274 c ... Code that sets A, B and C
2275 ENCODE (80, 9000, LINE) A, B, C
2276 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2283 CHARACTER(LEN=80) LINE
2285 c ... Code that sets A, B and C
2286 WRITE (UNIT=LINE, FMT=9000) A, B, C
2287 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2291 @node Variable FORMAT expressions
2292 @subsection Variable @code{FORMAT} expressions
2293 @cindex @code{FORMAT}
2295 A variable @code{FORMAT} expression is format statement which includes
2296 angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU
2297 Fortran does not support this legacy extension. The effect of variable
2298 format expressions can be reproduced by using the more powerful (and
2299 standard) combination of internal output and string formats. For example,
2300 replace a code fragment like this:
2311 c Variable declaration
2312 CHARACTER(LEN=20) FMT
2314 c Other code here...
2316 WRITE(FMT,'("(I", I0, ")")') N+1
2324 c Variable declaration
2325 CHARACTER(LEN=20) FMT
2327 c Other code here...
2330 WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1
2334 @node Alternate complex function syntax
2335 @subsection Alternate complex function syntax
2336 @cindex Complex function
2338 Some Fortran compilers, including @command{g77}, let the user declare
2339 complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as
2340 well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy
2341 extensions. @command{gfortran} accepts the latter form, which is more
2342 common, but not the former.
2345 @node Volatile COMMON blocks
2346 @subsection Volatile @code{COMMON} blocks
2347 @cindex @code{VOLATILE}
2348 @cindex @code{COMMON}
2350 Some Fortran compilers, including @command{g77}, let the user declare
2351 @code{COMMON} with the @code{VOLATILE} attribute. This is
2352 invalid standard Fortran syntax and is not supported by
2353 @command{gfortran}. Note that @command{gfortran} accepts
2354 @code{VOLATILE} variables in @code{COMMON} blocks since revision 4.3.
2358 @c ---------------------------------------------------------------------
2359 @c Mixed-Language Programming
2360 @c ---------------------------------------------------------------------
2362 @node Mixed-Language Programming
2363 @chapter Mixed-Language Programming
2364 @cindex Interoperability
2365 @cindex Mixed-language programming
2368 * Interoperability with C::
2369 * GNU Fortran Compiler Directives::
2370 * Non-Fortran Main Program::
2371 * Naming and argument-passing conventions::
2374 This chapter is about mixed-language interoperability, but also applies
2375 if one links Fortran code compiled by different compilers. In most cases,
2376 use of the C Binding features of the Fortran 2003 standard is sufficient,
2377 and their use is highly recommended.
2380 @node Interoperability with C
2381 @section Interoperability with C
2385 * Derived Types and struct::
2386 * Interoperable Global Variables::
2387 * Interoperable Subroutines and Functions::
2388 * Working with Pointers::
2389 * Further Interoperability of Fortran with C::
2392 Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a
2393 standardized way to generate procedure and derived-type
2394 declarations and global variables which are interoperable with C
2395 (ISO/IEC 9899:1999). The @code{bind(C)} attribute has been added
2396 to inform the compiler that a symbol shall be interoperable with C;
2397 also, some constraints are added. Note, however, that not
2398 all C features have a Fortran equivalent or vice versa. For instance,
2399 neither C's unsigned integers nor C's functions with variable number
2400 of arguments have an equivalent in Fortran.
2402 Note that array dimensions are reversely ordered in C and that arrays in
2403 C always start with index 0 while in Fortran they start by default with
2404 1. Thus, an array declaration @code{A(n,m)} in Fortran matches
2405 @code{A[m][n]} in C and accessing the element @code{A(i,j)} matches
2406 @code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]};
2407 assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}).
2409 @node Intrinsic Types
2410 @subsection Intrinsic Types
2412 In order to ensure that exactly the same variable type and kind is used
2413 in C and Fortran, the named constants shall be used which are defined in the
2414 @code{ISO_C_BINDING} intrinsic module. That module contains named constants
2415 for kind parameters and character named constants for the escape sequences
2416 in C. For a list of the constants, see @ref{ISO_C_BINDING}.
2418 For logical types, please note that the Fortran standard only guarantees
2419 interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
2420 logicals and C99 defines that @code{true} has the value 1 and @code{false}
2421 the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL}
2422 (with any kind parameter) gives an undefined result. (Passing other integer
2423 values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the
2424 integer is explicitly or implicitly casted to @code{_Bool}.)
2428 @node Derived Types and struct
2429 @subsection Derived Types and struct
2431 For compatibility of derived types with @code{struct}, one needs to use
2432 the @code{BIND(C)} attribute in the type declaration. For instance, the
2433 following type declaration
2437 TYPE, BIND(C) :: myType
2438 INTEGER(C_INT) :: i1, i2
2439 INTEGER(C_SIGNED_CHAR) :: i3
2440 REAL(C_DOUBLE) :: d1
2441 COMPLEX(C_FLOAT_COMPLEX) :: c1
2442 CHARACTER(KIND=C_CHAR) :: str(5)
2446 matches the following @code{struct} declaration in C
2451 /* Note: "char" might be signed or unsigned. */
2459 Derived types with the C binding attribute shall not have the @code{sequence}
2460 attribute, type parameters, the @code{extends} attribute, nor type-bound
2461 procedures. Every component must be of interoperable type and kind and may not
2462 have the @code{pointer} or @code{allocatable} attribute. The names of the
2463 components are irrelevant for interoperability.
2465 As there exist no direct Fortran equivalents, neither unions nor structs
2466 with bit field or variable-length array members are interoperable.
2468 @node Interoperable Global Variables
2469 @subsection Interoperable Global Variables
2471 Variables can be made accessible from C using the C binding attribute,
2472 optionally together with specifying a binding name. Those variables
2473 have to be declared in the declaration part of a @code{MODULE},
2474 be of interoperable type, and have neither the @code{pointer} nor
2475 the @code{allocatable} attribute.
2481 integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag
2482 type(myType), bind(C) :: tp
2486 Here, @code{_MyProject_flags} is the case-sensitive name of the variable
2487 as seen from C programs while @code{global_flag} is the case-insensitive
2488 name as seen from Fortran. If no binding name is specified, as for
2489 @var{tp}, the C binding name is the (lowercase) Fortran binding name.
2490 If a binding name is specified, only a single variable may be after the
2491 double colon. Note of warning: You cannot use a global variable to
2492 access @var{errno} of the C library as the C standard allows it to be
2493 a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead.
2495 @node Interoperable Subroutines and Functions
2496 @subsection Interoperable Subroutines and Functions
2498 Subroutines and functions have to have the @code{BIND(C)} attribute to
2499 be compatible with C. The dummy argument declaration is relatively
2500 straightforward. However, one needs to be careful because C uses
2501 call-by-value by default while Fortran behaves usually similar to
2502 call-by-reference. Furthermore, strings and pointers are handled
2503 differently. Note that in Fortran 2003 and 2008 only explicit size
2504 and assumed-size arrays are supported but not assumed-shape or
2505 deferred-shape (i.e. allocatable or pointer) arrays. However, those
2506 are allowed since the Technical Specification 29113, see
2507 @ref{Further Interoperability of Fortran with C}
2509 To pass a variable by value, use the @code{VALUE} attribute.
2510 Thus, the following C prototype
2513 @code{int func(int i, int *j)}
2516 matches the Fortran declaration
2519 integer(c_int) function func(i,j)
2520 use iso_c_binding, only: c_int
2521 integer(c_int), VALUE :: i
2525 Note that pointer arguments also frequently need the @code{VALUE} attribute,
2526 see @ref{Working with Pointers}.
2528 Strings are handled quite differently in C and Fortran. In C a string
2529 is a @code{NUL}-terminated array of characters while in Fortran each string
2530 has a length associated with it and is thus not terminated (by e.g.
2531 @code{NUL}). For example, if one wants to use the following C function,
2535 void print_C(char *string) /* equivalent: char string[] */
2537 printf("%s\n", string);
2541 to print ``Hello World'' from Fortran, one can call it using
2544 use iso_c_binding, only: C_CHAR, C_NULL_CHAR
2546 subroutine print_c(string) bind(C, name="print_C")
2547 use iso_c_binding, only: c_char
2548 character(kind=c_char) :: string(*)
2549 end subroutine print_c
2551 call print_c(C_CHAR_"Hello World"//C_NULL_CHAR)
2554 As the example shows, one needs to ensure that the
2555 string is @code{NUL} terminated. Additionally, the dummy argument
2556 @var{string} of @code{print_C} is a length-one assumed-size
2557 array; using @code{character(len=*)} is not allowed. The example
2558 above uses @code{c_char_"Hello World"} to ensure the string
2559 literal has the right type; typically the default character
2560 kind and @code{c_char} are the same and thus @code{"Hello World"}
2561 is equivalent. However, the standard does not guarantee this.
2563 The use of strings is now further illustrated using the C library
2564 function @code{strncpy}, whose prototype is
2567 char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
2570 The function @code{strncpy} copies at most @var{n} characters from
2571 string @var{s2} to @var{s1} and returns @var{s1}. In the following
2572 example, we ignore the return value:
2577 character(len=30) :: str,str2
2579 ! Ignore the return value of strncpy -> subroutine
2580 ! "restrict" is always assumed if we do not pass a pointer
2581 subroutine strncpy(dest, src, n) bind(C)
2583 character(kind=c_char), intent(out) :: dest(*)
2584 character(kind=c_char), intent(in) :: src(*)
2585 integer(c_size_t), value, intent(in) :: n
2586 end subroutine strncpy
2588 str = repeat('X',30) ! Initialize whole string with 'X'
2589 call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, &
2590 len(c_char_"Hello World",kind=c_size_t))
2591 print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX"
2595 The intrinsic procedures are described in @ref{Intrinsic Procedures}.
2597 @node Working with Pointers
2598 @subsection Working with Pointers
2600 C pointers are represented in Fortran via the special opaque derived type
2601 @code{type(c_ptr)} (with private components). Thus one needs to
2602 use intrinsic conversion procedures to convert from or to C pointers.
2604 For some applications, using an assumed type (@code{TYPE(*)}) can be an
2605 alternative to a C pointer; see
2606 @ref{Further Interoperability of Fortran with C}.
2612 type(c_ptr) :: cptr1, cptr2
2613 integer, target :: array(7), scalar
2614 integer, pointer :: pa(:), ps
2615 cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the
2616 ! array is contiguous if required by the C
2618 cptr2 = c_loc(scalar)
2619 call c_f_pointer(cptr2, ps)
2620 call c_f_pointer(cptr2, pa, shape=[7])
2623 When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument
2626 If a pointer is a dummy-argument of an interoperable procedure, it usually
2627 has to be declared using the @code{VALUE} attribute. @code{void*}
2628 matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone
2629 matches @code{void**}.
2631 Procedure pointers are handled analogously to pointers; the C type is
2632 @code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are
2633 @code{C_F_PROCPOINTER} and @code{C_FUNLOC}.
2635 Let us consider two examples of actually passing a procedure pointer from
2636 C to Fortran and vice versa. Note that these examples are also very
2637 similar to passing ordinary pointers between both languages. First,
2638 consider this code in C:
2641 /* Procedure implemented in Fortran. */
2642 void get_values (void (*)(double));
2644 /* Call-back routine we want called from Fortran. */
2648 printf ("Number is %f.\n", x);
2651 /* Call Fortran routine and pass call-back to it. */
2655 get_values (&print_it);
2659 A matching implementation for @code{get_values} in Fortran, that correctly
2660 receives the procedure pointer from C and is able to call it, is given
2661 in the following @code{MODULE}:
2667 ! Define interface of call-back routine.
2669 SUBROUTINE callback (x)
2670 USE, INTRINSIC :: ISO_C_BINDING
2671 REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x
2672 END SUBROUTINE callback
2677 ! Define C-bound procedure.
2678 SUBROUTINE get_values (cproc) BIND(C)
2679 USE, INTRINSIC :: ISO_C_BINDING
2680 TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc
2682 PROCEDURE(callback), POINTER :: proc
2684 ! Convert C to Fortran procedure pointer.
2685 CALL C_F_PROCPOINTER (cproc, proc)
2688 CALL proc (1.0_C_DOUBLE)
2689 CALL proc (-42.0_C_DOUBLE)
2690 CALL proc (18.12_C_DOUBLE)
2691 END SUBROUTINE get_values
2696 Next, we want to call a C routine that expects a procedure pointer argument
2697 and pass it a Fortran procedure (which clearly must be interoperable!).
2698 Again, the C function may be:
2702 call_it (int (*func)(int), int arg)
2708 It can be used as in the following Fortran code:
2712 USE, INTRINSIC :: ISO_C_BINDING
2715 ! Define interface of C function.
2717 INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C)
2718 USE, INTRINSIC :: ISO_C_BINDING
2719 TYPE(C_FUNPTR), INTENT(IN), VALUE :: func
2720 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
2721 END FUNCTION call_it
2726 ! Define procedure passed to C function.
2727 ! It must be interoperable!
2728 INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C)
2729 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
2730 double_it = arg + arg
2731 END FUNCTION double_it
2734 SUBROUTINE foobar ()
2735 TYPE(C_FUNPTR) :: cproc
2736 INTEGER(KIND=C_INT) :: i
2738 ! Get C procedure pointer.
2739 cproc = C_FUNLOC (double_it)
2742 DO i = 1_C_INT, 10_C_INT
2743 PRINT *, call_it (cproc, i)
2745 END SUBROUTINE foobar
2750 @node Further Interoperability of Fortran with C
2751 @subsection Further Interoperability of Fortran with C
2753 The Technical Specification ISO/IEC TS 29113:2012 on further
2754 interoperability of Fortran with C extends the interoperability support
2755 of Fortran 2003 and Fortran 2008. Besides removing some restrictions
2756 and constraints, it adds assumed-type (@code{TYPE(*)}) and assumed-rank
2757 (@code{dimension}) variables and allows for interoperability of
2758 assumed-shape, assumed-rank and deferred-shape arrays, including
2759 allocatables and pointers.
2761 Note: Currently, GNU Fortran does not support the array descriptor
2762 (dope vector) as specified in the Technical Specification, but uses
2763 an array descriptor with different fields. The Chasm Language
2764 Interoperability Tools, @url{http://chasm-interop.sourceforge.net/},
2765 provide an interface to GNU Fortran's array descriptor.
2767 The Technical Specification adds the following new features, which
2768 are supported by GNU Fortran:
2772 @item The @code{ASYNCHRONOUS} attribute has been clarified and
2773 extended to allow its use with asynchronous communication in
2774 user-provided libraries such as in implementations of the
2775 Message Passing Interface specification.
2777 @item Many constraints have been relaxed, in particular for
2778 the @code{C_LOC} and @code{C_F_POINTER} intrinsics.
2780 @item The @code{OPTIONAL} attribute is now allowed for dummy
2781 arguments; an absent argument matches a @code{NULL} pointer.
2783 @item Assumed types (@code{TYPE(*)}) have been added, which may
2784 only be used for dummy arguments. They are unlimited polymorphic
2785 but contrary to @code{CLASS(*)} they do not contain any type
2786 information, similar to C's @code{void *} pointers. Expressions
2787 of any type and kind can be passed; thus, it can be used as
2788 replacement for @code{TYPE(C_PTR)}, avoiding the use of
2789 @code{C_LOC} in the caller.
2791 Note, however, that @code{TYPE(*)} only accepts scalar arguments,
2792 unless the @code{DIMENSION} is explicitly specified. As
2793 @code{DIMENSION(*)} only supports array (including array elements) but
2794 no scalars, it is not a full replacement for @code{C_LOC}. On the
2795 other hand, assumed-type assumed-rank dummy arguments
2796 (@code{TYPE(*), DIMENSION(..)}) allow for both scalars and arrays, but
2797 require special code on the callee side to handle the array descriptor.
2799 @item Assumed-rank arrays (@code{DIMENSION(..)}) as dummy argument
2800 allow that scalars and arrays of any rank can be passed as actual
2801 argument. As the Technical Specification does not provide for direct
2802 means to operate with them, they have to be used either from the C side
2803 or be converted using @code{C_LOC} and @code{C_F_POINTER} to scalars
2804 or arrays of a specific rank. The rank can be determined using the
2805 @code{RANK} intrinisic.
2809 Currently unimplemented:
2813 @item GNU Fortran always uses an array descriptor, which does not
2814 match the one of the Technical Specification. The
2815 @code{ISO_Fortran_binding.h} header file and the C functions it
2816 specifies are not available.
2818 @item Using assumed-shape, assumed-rank and deferred-shape arrays in
2819 @code{BIND(C)} procedures is not fully supported. In particular,
2820 C interoperable strings of other length than one are not supported
2821 as this requires the new array descriptor.
2825 @node GNU Fortran Compiler Directives
2826 @section GNU Fortran Compiler Directives
2828 The Fortran standard describes how a conforming program shall
2829 behave; however, the exact implementation is not standardized. In order
2830 to allow the user to choose specific implementation details, compiler
2831 directives can be used to set attributes of variables and procedures
2832 which are not part of the standard. Whether a given attribute is
2833 supported and its exact effects depend on both the operating system and
2834 on the processor; see
2835 @ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)}
2838 For procedures and procedure pointers, the following attributes can
2839 be used to change the calling convention:
2842 @item @code{CDECL} -- standard C calling convention
2843 @item @code{STDCALL} -- convention where the called procedure pops the stack
2844 @item @code{FASTCALL} -- part of the arguments are passed via registers
2845 instead using the stack
2848 Besides changing the calling convention, the attributes also influence
2849 the decoration of the symbol name, e.g., by a leading underscore or by
2850 a trailing at-sign followed by the number of bytes on the stack. When
2851 assigning a procedure to a procedure pointer, both should use the same
2854 On some systems, procedures and global variables (module variables and
2855 @code{COMMON} blocks) need special handling to be accessible when they
2856 are in a shared library. The following attributes are available:
2859 @item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL
2860 @item @code{DLLIMPORT} -- reference the function or variable using a
2864 For dummy arguments, the @code{NO_ARG_CHECK} attribute can be used; in
2865 other compilers, it is also known as @code{IGNORE_TKR}. For dummy arguments
2866 with this attribute actual arguments of any type and kind (similar to
2867 @code{TYPE(*)}), scalars and arrays of any rank (no equivalent
2868 in Fortran standard) are accepted. As with @code{TYPE(*)}, the argument
2869 is unlimited polymorphic and no type information is available.
2870 Additionally, the argument may only be passed to dummy arguments
2871 with the @code{NO_ARG_CHECK} attribute and as argument to the
2872 @code{PRESENT} intrinsic function and to @code{C_LOC} of the
2873 @code{ISO_C_BINDING} module.
2875 Variables with @code{NO_ARG_CHECK} attribute shall be of assumed-type
2876 (@code{TYPE(*)}; recommended) or of type @code{INTEGER}, @code{LOGICAL},
2877 @code{REAL} or @code{COMPLEX}. They shall not have the @code{ALLOCATE},
2878 @code{CODIMENSION}, @code{INTENT(OUT)}, @code{POINTER} or @code{VALUE}
2879 attribute; furthermore, they shall be either scalar or of assumed-size
2880 (@code{dimension(*)}). As @code{TYPE(*)}, the @code{NO_ARG_CHECK} attribute
2881 requires an explicit interface.
2884 @item @code{NO_ARG_CHECK} -- disable the type, kind and rank checking
2888 The attributes are specified using the syntax
2890 @code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list}
2892 where in free-form source code only whitespace is allowed before @code{!GCC$}
2893 and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall
2894 start in the first column.
2896 For procedures, the compiler directives shall be placed into the body
2897 of the procedure; for variables and procedure pointers, they shall be in
2898 the same declaration part as the variable or procedure pointer.
2902 @node Non-Fortran Main Program
2903 @section Non-Fortran Main Program
2906 * _gfortran_set_args:: Save command-line arguments
2907 * _gfortran_set_options:: Set library option flags
2908 * _gfortran_set_convert:: Set endian conversion
2909 * _gfortran_set_record_marker:: Set length of record markers
2910 * _gfortran_set_fpe:: Set when a Floating Point Exception should be raised
2911 * _gfortran_set_max_subrecord_length:: Set subrecord length
2914 Even if you are doing mixed-language programming, it is very
2915 likely that you do not need to know or use the information in this
2916 section. Since it is about the internal structure of GNU Fortran,
2917 it may also change in GCC minor releases.
2919 When you compile a @code{PROGRAM} with GNU Fortran, a function
2920 with the name @code{main} (in the symbol table of the object file)
2921 is generated, which initializes the libgfortran library and then
2922 calls the actual program which uses the name @code{MAIN__}, for
2923 historic reasons. If you link GNU Fortran compiled procedures
2924 to, e.g., a C or C++ program or to a Fortran program compiled by
2925 a different compiler, the libgfortran library is not initialized
2926 and thus a few intrinsic procedures do not work properly, e.g.
2927 those for obtaining the command-line arguments.
2929 Therefore, if your @code{PROGRAM} is not compiled with
2930 GNU Fortran and the GNU Fortran compiled procedures require
2931 intrinsics relying on the library initialization, you need to
2932 initialize the library yourself. Using the default options,
2933 gfortran calls @code{_gfortran_set_args} and
2934 @code{_gfortran_set_options}. The initialization of the former
2935 is needed if the called procedures access the command line
2936 (and for backtracing); the latter sets some flags based on the
2937 standard chosen or to enable backtracing. In typical programs,
2938 it is not necessary to call any initialization function.
2940 If your @code{PROGRAM} is compiled with GNU Fortran, you shall
2941 not call any of the following functions. The libgfortran
2942 initialization functions are shown in C syntax but using C
2943 bindings they are also accessible from Fortran.
2946 @node _gfortran_set_args
2947 @subsection @code{_gfortran_set_args} --- Save command-line arguments
2948 @fnindex _gfortran_set_args
2949 @cindex libgfortran initialization, set_args
2952 @item @emph{Description}:
2953 @code{_gfortran_set_args} saves the command-line arguments; this
2954 initialization is required if any of the command-line intrinsics
2955 is called. Additionally, it shall be called if backtracing is
2956 enabled (see @code{_gfortran_set_options}).
2958 @item @emph{Syntax}:
2959 @code{void _gfortran_set_args (int argc, char *argv[])}
2961 @item @emph{Arguments}:
2962 @multitable @columnfractions .15 .70
2963 @item @var{argc} @tab number of command line argument strings
2964 @item @var{argv} @tab the command-line argument strings; argv[0]
2965 is the pathname of the executable itself.
2968 @item @emph{Example}:
2970 int main (int argc, char *argv[])
2972 /* Initialize libgfortran. */
2973 _gfortran_set_args (argc, argv);
2980 @node _gfortran_set_options
2981 @subsection @code{_gfortran_set_options} --- Set library option flags
2982 @fnindex _gfortran_set_options
2983 @cindex libgfortran initialization, set_options
2986 @item @emph{Description}:
2987 @code{_gfortran_set_options} sets several flags related to the Fortran
2988 standard to be used, whether backtracing should be enabled
2989 and whether range checks should be performed. The syntax allows for
2990 upward compatibility since the number of passed flags is specified; for
2991 non-passed flags, the default value is used. See also
2992 @pxref{Code Gen Options}. Please note that not all flags are actually
2995 @item @emph{Syntax}:
2996 @code{void _gfortran_set_options (int num, int options[])}
2998 @item @emph{Arguments}:
2999 @multitable @columnfractions .15 .70
3000 @item @var{num} @tab number of options passed
3001 @item @var{argv} @tab The list of flag values
3004 @item @emph{option flag list}:
3005 @multitable @columnfractions .15 .70
3006 @item @var{option}[0] @tab Allowed standard; can give run-time errors
3007 if e.g. an input-output edit descriptor is invalid in a given standard.
3008 Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1),
3009 @code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4), @code{GFC_STD_F95}
3010 (8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU} (32),
3011 @code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128),
3012 @code{GFC_STD_F2008_OBS} (256) and GFC_STD_F2008_TS (512). Default:
3013 @code{GFC_STD_F95_OBS | GFC_STD_F95_DEL | GFC_STD_F95 | GFC_STD_F2003
3014 | GFC_STD_F2008 | GFC_STD_F2008_TS | GFC_STD_F2008_OBS | GFC_STD_F77
3015 | GFC_STD_GNU | GFC_STD_LEGACY}.
3016 @item @var{option}[1] @tab Standard-warning flag; prints a warning to
3017 standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}.
3018 @item @var{option}[2] @tab If non zero, enable pedantic checking.
3020 @item @var{option}[3] @tab Unused.
3021 @item @var{option}[4] @tab If non zero, enable backtracing on run-time
3022 errors. Default: off. (Default in the compiler: on.)
3023 Note: Installs a signal handler and requires command-line
3024 initialization using @code{_gfortran_set_args}.
3025 @item @var{option}[5] @tab If non zero, supports signed zeros.
3027 @item @var{option}[6] @tab Enables run-time checking. Possible values
3028 are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2),
3029 GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (16), GFC_RTCHECK_POINTER (32).
3031 @item @var{option}[7] @tab Unused.
3032 @item @var{option}[8] @tab Show a warning when invoking @code{STOP} and
3033 @code{ERROR STOP} if a floating-point exception occurred. Possible values
3034 are (bitwise or-ed) @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3035 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3036 @code{GFC_FPE_UNDERFLOW} (16), @code{GFC_FPE_INEXACT} (32). Default: None (0).
3037 (Default in the compiler: @code{GFC_FPE_INVALID | GFC_FPE_DENORMAL |
3038 GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW}.)
3041 @item @emph{Example}:
3043 /* Use gfortran 4.9 default options. */
3044 static int options[] = @{68, 511, 0, 0, 1, 1, 0, 0, 31@};
3045 _gfortran_set_options (9, &options);
3050 @node _gfortran_set_convert
3051 @subsection @code{_gfortran_set_convert} --- Set endian conversion
3052 @fnindex _gfortran_set_convert
3053 @cindex libgfortran initialization, set_convert
3056 @item @emph{Description}:
3057 @code{_gfortran_set_convert} set the representation of data for
3060 @item @emph{Syntax}:
3061 @code{void _gfortran_set_convert (int conv)}
3063 @item @emph{Arguments}:
3064 @multitable @columnfractions .15 .70
3065 @item @var{conv} @tab Endian conversion, possible values:
3066 GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1),
3067 GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3).
3070 @item @emph{Example}:
3072 int main (int argc, char *argv[])
3074 /* Initialize libgfortran. */
3075 _gfortran_set_args (argc, argv);
3076 _gfortran_set_convert (1);
3083 @node _gfortran_set_record_marker
3084 @subsection @code{_gfortran_set_record_marker} --- Set length of record markers
3085 @fnindex _gfortran_set_record_marker
3086 @cindex libgfortran initialization, set_record_marker
3089 @item @emph{Description}:
3090 @code{_gfortran_set_record_marker} sets the length of record markers
3091 for unformatted files.
3093 @item @emph{Syntax}:
3094 @code{void _gfortran_set_record_marker (int val)}
3096 @item @emph{Arguments}:
3097 @multitable @columnfractions .15 .70
3098 @item @var{val} @tab Length of the record marker; valid values
3099 are 4 and 8. Default is 4.
3102 @item @emph{Example}:
3104 int main (int argc, char *argv[])
3106 /* Initialize libgfortran. */
3107 _gfortran_set_args (argc, argv);
3108 _gfortran_set_record_marker (8);
3115 @node _gfortran_set_fpe
3116 @subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps
3117 @fnindex _gfortran_set_fpe
3118 @cindex libgfortran initialization, set_fpe
3121 @item @emph{Description}:
3122 @code{_gfortran_set_fpe} enables floating point exception traps for
3123 the specified exceptions. On most systems, this will result in a
3124 SIGFPE signal being sent and the program being aborted.
3126 @item @emph{Syntax}:
3127 @code{void _gfortran_set_fpe (int val)}
3129 @item @emph{Arguments}:
3130 @multitable @columnfractions .15 .70
3131 @item @var{option}[0] @tab IEEE exceptions. Possible values are
3132 (bitwise or-ed) zero (0, default) no trapping,
3133 @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3134 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3135 @code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32).
3138 @item @emph{Example}:
3140 int main (int argc, char *argv[])
3142 /* Initialize libgfortran. */
3143 _gfortran_set_args (argc, argv);
3144 /* FPE for invalid operations such as SQRT(-1.0). */
3145 _gfortran_set_fpe (1);
3152 @node _gfortran_set_max_subrecord_length
3153 @subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length
3154 @fnindex _gfortran_set_max_subrecord_length
3155 @cindex libgfortran initialization, set_max_subrecord_length
3158 @item @emph{Description}:
3159 @code{_gfortran_set_max_subrecord_length} set the maximum length
3160 for a subrecord. This option only makes sense for testing and
3161 debugging of unformatted I/O.
3163 @item @emph{Syntax}:
3164 @code{void _gfortran_set_max_subrecord_length (int val)}
3166 @item @emph{Arguments}:
3167 @multitable @columnfractions .15 .70
3168 @item @var{val} @tab the maximum length for a subrecord;
3169 the maximum permitted value is 2147483639, which is also
3173 @item @emph{Example}:
3175 int main (int argc, char *argv[])
3177 /* Initialize libgfortran. */
3178 _gfortran_set_args (argc, argv);
3179 _gfortran_set_max_subrecord_length (8);
3186 @node Naming and argument-passing conventions
3187 @section Naming and argument-passing conventions
3189 This section gives an overview about the naming convention of procedures
3190 and global variables and about the argument passing conventions used by
3191 GNU Fortran. If a C binding has been specified, the naming convention
3192 and some of the argument-passing conventions change. If possible,
3193 mixed-language and mixed-compiler projects should use the better defined
3194 C binding for interoperability. See @pxref{Interoperability with C}.
3197 * Naming conventions::
3198 * Argument passing conventions::
3202 @node Naming conventions
3203 @subsection Naming conventions
3205 According the Fortran standard, valid Fortran names consist of a letter
3206 between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0},
3207 @code{1} to @code{9} and underscores (@code{_}) with the restriction
3208 that names may only start with a letter. As vendor extension, the
3209 dollar sign (@code{$}) is additionally permitted with the option
3210 @option{-fdollar-ok}, but not as first character and only if the
3211 target system supports it.
3213 By default, the procedure name is the lower-cased Fortran name with an
3214 appended underscore (@code{_}); using @option{-fno-underscoring} no
3215 underscore is appended while @code{-fsecond-underscore} appends two
3216 underscores. Depending on the target system and the calling convention,
3217 the procedure might be additionally dressed; for instance, on 32bit
3218 Windows with @code{stdcall}, an at-sign @code{@@} followed by an integer
3219 number is appended. For the changing the calling convention, see
3220 @pxref{GNU Fortran Compiler Directives}.
3222 For common blocks, the same convention is used, i.e. by default an
3223 underscore is appended to the lower-cased Fortran name. Blank commons
3224 have the name @code{__BLNK__}.
3226 For procedures and variables declared in the specification space of a
3227 module, the name is formed by @code{__}, followed by the lower-cased
3228 module name, @code{_MOD_}, and the lower-cased Fortran name. Note that
3229 no underscore is appended.
3232 @node Argument passing conventions
3233 @subsection Argument passing conventions
3235 Subroutines do not return a value (matching C99's @code{void}) while
3236 functions either return a value as specified in the platform ABI or
3237 the result variable is passed as hidden argument to the function and
3238 no result is returned. A hidden result variable is used when the
3239 result variable is an array or of type @code{CHARACTER}.
3241 Arguments are passed according to the platform ABI. In particular,
3242 complex arguments might not be compatible to a struct with two real
3243 components for the real and imaginary part. The argument passing
3244 matches the one of C99's @code{_Complex}. Functions with scalar
3245 complex result variables return their value and do not use a
3246 by-reference argument. Note that with the @option{-ff2c} option,
3247 the argument passing is modified and no longer completely matches
3248 the platform ABI. Some other Fortran compilers use @code{f2c}
3249 semantic by default; this might cause problems with
3252 GNU Fortran passes most arguments by reference, i.e. by passing a
3253 pointer to the data. Note that the compiler might use a temporary
3254 variable into which the actual argument has been copied, if required
3255 semantically (copy-in/copy-out).
3257 For arguments with @code{ALLOCATABLE} and @code{POINTER}
3258 attribute (including procedure pointers), a pointer to the pointer
3259 is passed such that the pointer address can be modified in the
3262 For dummy arguments with the @code{VALUE} attribute: Scalar arguments
3263 of the type @code{INTEGER}, @code{LOGICAL}, @code{REAL} and
3264 @code{COMPLEX} are passed by value according to the platform ABI.
3265 (As vendor extension and not recommended, using @code{%VAL()} in the
3266 call to a procedure has the same effect.) For @code{TYPE(C_PTR)} and
3267 procedure pointers, the pointer itself is passed such that it can be
3268 modified without affecting the caller.
3269 @c FIXME: Document how VALUE is handled for CHARACTER, TYPE,
3270 @c CLASS and arrays, i.e. whether the copy-in is done in the caller
3271 @c or in the callee.
3273 For Boolean (@code{LOGICAL}) arguments, please note that GCC expects
3274 only the integer value 0 and 1. If a GNU Fortran @code{LOGICAL}
3275 variable contains another integer value, the result is undefined.
3276 As some other Fortran compilers use @math{-1} for @code{.TRUE.},
3277 extra care has to be taken -- such as passing the value as
3278 @code{INTEGER}. (The same value restriction also applies to other
3279 front ends of GCC, e.g. to GCC's C99 compiler for @code{_Bool}
3280 or GCC's Ada compiler for @code{Boolean}.)
3282 For arguments of @code{CHARACTER} type, the character length is passed
3283 as hidden argument. For deferred-length strings, the value is passed
3284 by reference, otherwise by value. The character length has the type
3285 @code{INTEGER(kind=4)}. Note with C binding, @code{CHARACTER(len=1)}
3286 result variables are returned according to the platform ABI and no
3287 hidden length argument is used for dummy arguments; with @code{VALUE},
3288 those variables are passed by value.
3290 For @code{OPTIONAL} dummy arguments, an absent argument is denoted
3291 by a NULL pointer, except for scalar dummy arguments of type
3292 @code{INTEGER}, @code{LOGICAL}, @code{REAL} and @code{COMPLEX}
3293 which have the @code{VALUE} attribute. For those, a hidden Boolean
3294 argument (@code{logical(kind=C_bool),value}) is used to indicate
3295 whether the argument is present.
3297 Arguments which are assumed-shape, assumed-rank or deferred-rank
3298 arrays or, with @option{-fcoarray=lib}, allocatable scalar coarrays use
3299 an array descriptor. All other arrays pass the address of the
3300 first element of the array. With @option{-fcoarray=lib}, the token
3301 and the offset belonging to nonallocatable coarrays dummy arguments
3302 are passed as hidden argument along the character length hidden
3303 arguments. The token is an oparque pointer identifying the coarray
3304 and the offset is a passed-by-value integer of kind @code{C_PTRDIFF_T},
3305 denoting the byte offset between the base address of the coarray and
3306 the passed scalar or first element of the passed array.
3308 The arguments are passed in the following order
3310 @item Result variable, when the function result is passed by reference
3311 @item Character length of the function result, if it is a of type
3312 @code{CHARACTER} and no C binding is used
3313 @item The arguments in the order in which they appear in the Fortran
3315 @item The the present status for optional arguments with value attribute,
3316 which are internally passed by value
3317 @item The character length and/or coarray token and offset for the first
3318 argument which is a @code{CHARACTER} or a nonallocatable coarray dummy
3319 argument, followed by the hidden arguments of the next dummy argument
3324 @c ---------------------------------------------------------------------
3325 @c Coarray Programming
3326 @c ---------------------------------------------------------------------
3328 @node Coarray Programming
3329 @chapter Coarray Programming
3333 * Type and enum ABI Documentation::
3334 * Function ABI Documentation::
3338 @node Type and enum ABI Documentation
3339 @section Type and enum ABI Documentation
3347 @subsection @code{caf_token_t}
3349 Typedef of type @code{void *} on the compiler side. Can be any data
3350 type on the library side.
3352 @node caf_register_t
3353 @subsection @code{caf_register_t}
3355 Indicates which kind of coarray variable should be registered.
3358 typedef enum caf_register_t {
3359 CAF_REGTYPE_COARRAY_STATIC,
3360 CAF_REGTYPE_COARRAY_ALLOC,
3361 CAF_REGTYPE_LOCK_STATIC,
3362 CAF_REGTYPE_LOCK_ALLOC,
3363 CAF_REGTYPE_CRITICAL,
3364 CAF_REGTYPE_EVENT_STATIC,
3365 CAF_REGTYPE_EVENT_ALLOC
3371 @node Function ABI Documentation
3372 @section Function ABI Documentation
3375 * _gfortran_caf_init:: Initialiation function
3376 * _gfortran_caf_finish:: Finalization function
3377 * _gfortran_caf_this_image:: Querying the image number
3378 * _gfortran_caf_num_images:: Querying the maximal number of images
3379 * _gfortran_caf_register:: Registering coarrays
3380 * _gfortran_caf_deregister:: Deregistering coarrays
3381 * _gfortran_caf_send:: Sending data from a local image to a remote image
3382 * _gfortran_caf_get:: Getting data from a remote image
3383 * _gfortran_caf_sendget:: Sending data between remote images
3384 * _gfortran_caf_lock:: Locking a lock variable
3385 * _gfortran_caf_unlock:: Unlocking a lock variable
3386 * _gfortran_caf_event_post:: Post an event
3387 * _gfortran_caf_event_wait:: Wait that an event occurred
3388 * _gfortran_caf_event_query:: Query event count
3389 * _gfortran_caf_sync_all:: All-image barrier
3390 * _gfortran_caf_sync_images:: Barrier for selected images
3391 * _gfortran_caf_sync_memory:: Wait for completion of segment-memory operations
3392 * _gfortran_caf_error_stop:: Error termination with exit code
3393 * _gfortran_caf_error_stop_str:: Error termination with string
3394 * _gfortran_caf_atomic_define:: Atomic variable assignment
3395 * _gfortran_caf_atomic_ref:: Atomic variable reference
3396 * _gfortran_caf_atomic_cas:: Atomic compare and swap
3397 * _gfortran_caf_atomic_op:: Atomic operation
3398 * _gfortran_caf_co_broadcast:: Sending data to all images
3399 * _gfortran_caf_co_max:: Collective maximum reduction
3400 * _gfortran_caf_co_min:: Collective minimum reduction
3401 * _gfortran_caf_co_sum:: Collective summing reduction
3402 * _gfortran_caf_co_reduce:: Generic collective reduction
3406 @node _gfortran_caf_init
3407 @subsection @code{_gfortran_caf_init} --- Initialiation function
3408 @cindex Coarray, _gfortran_caf_init
3411 @item @emph{Description}:
3412 This function is called at startup of the program before the Fortran main
3413 program, if the latter has been compiled with @option{-fcoarray=lib}.
3414 It takes as arguments the command-line arguments of the program. It is
3415 permitted to pass to @code{NULL} pointers as argument; if non-@code{NULL},
3416 the library is permitted to modify the arguments.
3418 @item @emph{Syntax}:
3419 @code{void _gfortran_caf_init (int *argc, char ***argv)}
3421 @item @emph{Arguments}:
3422 @multitable @columnfractions .15 .70
3423 @item @var{argc} @tab intent(inout) An integer pointer with the number of
3424 arguments passed to the program or @code{NULL}.
3425 @item @var{argv} @tab intent(inout) A pointer to an array of strings with the
3426 command-line arguments or @code{NULL}.
3430 The function is modelled after the initialization function of the Message
3431 Passing Interface (MPI) specification. Due to the way coarray registration
3432 works, it might not be the first call to the libaray. If the main program is
3433 not written in Fortran and only a library uses coarrays, it can happen that
3434 this function is never called. Therefore, it is recommended that the library
3435 does not rely on the passed arguments and whether the call has been done.
3439 @node _gfortran_caf_finish
3440 @subsection @code{_gfortran_caf_finish} --- Finalization function
3441 @cindex Coarray, _gfortran_caf_finish
3444 @item @emph{Description}:
3445 This function is called at the end of the Fortran main program, if it has
3446 been compiled with the @option{-fcoarray=lib} option.
3448 @item @emph{Syntax}:
3449 @code{void _gfortran_caf_finish (void)}
3452 For non-Fortran programs, it is recommended to call the function at the end
3453 of the main program. To ensure that the shutdown is also performed for
3454 programs where this function is not explicitly invoked, for instance
3455 non-Fortran programs or calls to the system's exit() function, the library
3456 can use a destructor function. Note that programs can also be terminated
3457 using the STOP and ERROR STOP statements; those use different library calls.
3461 @node _gfortran_caf_this_image
3462 @subsection @code{_gfortran_caf_this_image} --- Querying the image number
3463 @cindex Coarray, _gfortran_caf_this_image
3466 @item @emph{Description}:
3467 This function returns the current image number, which is a positive number.
3469 @item @emph{Syntax}:
3470 @code{int _gfortran_caf_this_image (int distance)}
3472 @item @emph{Arguments}:
3473 @multitable @columnfractions .15 .70
3474 @item @var{distance} @tab As specified for the @code{this_image} intrinsic
3475 in TS18508. Shall be a nonnegative number.
3479 If the Fortran intrinsic @code{this_image} is invoked without an argument, which
3480 is the only permitted form in Fortran 2008, GCC passes @code{0} as
3485 @node _gfortran_caf_num_images
3486 @subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images
3487 @cindex Coarray, _gfortran_caf_num_images
3490 @item @emph{Description}:
3491 This function returns the number of images in the current team, if
3492 @var{distance} is 0 or the number of images in the parent team at the specified
3493 distance. If failed is -1, the function returns the number of all images at
3494 the specified distance; if it is 0, the function returns the number of
3495 nonfailed images, and if it is 1, it returns the number of failed images.
3497 @item @emph{Syntax}:
3498 @code{int _gfortran_caf_num_images(int distance, int failed)}
3500 @item @emph{Arguments}:
3501 @multitable @columnfractions .15 .70
3502 @item @var{distance} @tab the distance from this image to the ancestor.
3504 @item @var{failed} @tab shall be -1, 0, or 1
3508 This function follows TS18508. If the num_image intrinsic has no arguments,
3509 the the compiler passes @code{distance=0} and @code{failed=-1} to the function.
3513 @node _gfortran_caf_register
3514 @subsection @code{_gfortran_caf_register} --- Registering coarrays
3515 @cindex Coarray, _gfortran_caf_deregister
3518 @item @emph{Description}:
3519 Allocates memory for a coarray and creates a token to identify the coarray. The
3520 function is called for both coarrays with @code{SAVE} attribute and using an
3521 explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a
3522 @code{NULL} pointer, the function shall abort with printing an error message
3523 and starting the error termination. If no error occurs and @var{STAT} is
3524 present, it shall be set to zero. Otherwise, it shall be set to a positive
3525 value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing
3526 the failure. The function shall return a pointer to the requested memory
3527 for the local image as a call to @code{malloc} would do.
3529 For @code{CAF_REGTYPE_COARRAY_STATIC} and @code{CAF_REGTYPE_COARRAY_ALLOC},
3530 the passed size is the byte size requested. For @code{CAF_REGTYPE_LOCK_STATIC},
3531 @code{CAF_REGTYPE_LOCK_ALLOC} and @code{CAF_REGTYPE_CRITICAL} it is the array
3532 size or one for a scalar.
3535 @item @emph{Syntax}:
3536 @code{void *caf_register (size_t size, caf_register_t type, caf_token_t *token,
3537 int *stat, char *errmsg, int errmsg_len)}
3539 @item @emph{Arguments}:
3540 @multitable @columnfractions .15 .70
3541 @item @var{size} @tab For normal coarrays, the byte size of the coarray to be
3542 allocated; for lock types and event types, the number of elements.
3543 @item @var{type} @tab one of the caf_register_t types.
3544 @item @var{token} @tab intent(out) An opaque pointer identifying the coarray.
3545 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
3547 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3548 an error message; may be NULL
3549 @item @var{errmsg_len} @tab the buffer size of errmsg.
3553 Nonalloatable coarrays have to be registered prior use from remote images.
3554 In order to guarantee this, they have to be registered before the main
3555 program. This can be achieved by creating constructor functions. That is what
3556 GCC does such that also nonallocatable coarrays the memory is allocated and no
3557 static memory is used. The token permits to identify the coarray; to the
3558 processor, the token is a nonaliasing pointer. The library can, for instance,
3559 store the base address of the coarray in the token, some handle or a more
3562 For normal coarrays, the returned pointer is used for accesses on the local
3563 image. For lock types, the value shall only used for checking the allocation
3564 status. Note that for critical blocks, the locking is only required on one
3565 image; in the locking statement, the processor shall always pass always an
3566 image index of one for critical-block lock variables
3567 (@code{CAF_REGTYPE_CRITICAL}). For lock types and critical-block variables,
3568 the initial value shall be unlocked (or, respecitively, not in critical
3569 section) such as the value false; for event types, the initial state should
3570 be no event, e.g. zero.
3574 @node _gfortran_caf_deregister
3575 @subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays
3576 @cindex Coarray, _gfortran_caf_deregister
3579 @item @emph{Description}:
3580 Called to free the memory of a coarray; the processor calls this function for
3581 automatic and explicit deallocation. In case of an error, this function shall
3582 fail with an error message, unless the @var{STAT} variable is not null.
3584 @item @emph{Syntax}:
3585 @code{void caf_deregister (const caf_token_t *token, int *stat, char *errmsg,
3588 @item @emph{Arguments}:
3589 @multitable @columnfractions .15 .70
3590 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
3591 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set
3592 to an error message; may be NULL
3593 @item @var{errmsg_len} @tab the buffer size of errmsg.
3597 For nonalloatable coarrays this function is never called. If a cleanup is
3598 required, it has to be handled via the finish, stop and error stop functions,
3599 and via destructors.
3603 @node _gfortran_caf_send
3604 @subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image
3605 @cindex Coarray, _gfortran_caf_send
3608 @item @emph{Description}:
3609 Called to send a scalar, an array section or whole array from a local
3610 to a remote image identified by the image_index.
3612 @item @emph{Syntax}:
3613 @code{void _gfortran_caf_send (caf_token_t token, size_t offset,
3614 int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
3615 gfc_descriptor_t *src, int dst_kind, int src_kind, bool may_require_tmp)}
3617 @item @emph{Arguments}:
3618 @multitable @columnfractions .15 .70
3619 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3620 @item @var{offset} @tab By which amount of bytes the actual data is shifted
3621 compared to the base address of the coarray.
3622 @item @var{image_index} @tab The ID of the remote image; must be a positive
3624 @item @var{dest} @tab intent(in) Array descriptor for the remote image for the
3625 bounds and the size. The base_addr shall not be accessed.
3626 @item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
3627 subscript of the destination array; the values are relative to the dimension
3628 triplet of the dest argument.
3629 @item @var{src} @tab intent(in) Array descriptor of the local array to be
3630 transferred to the remote image
3631 @item @var{dst_kind} @tab Kind of the destination argument
3632 @item @var{src_kind} @tab Kind of the source argument
3633 @item @var{may_require_tmp} @tab The variable is false it is known at compile
3634 time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
3635 or partially) such that walking @var{src} and @var{dest} in element wise
3636 element order (honoring the stride value) will not lead to wrong results.
3637 Otherwise, the value is true.
3641 It is permitted to have image_id equal the current image; the memory of the
3642 send-to and the send-from might (partially) overlap in that case. The
3643 implementation has to take care that it handles this case, e.g. using
3644 @code{memmove} which handles (partially) overlapping memory. If
3645 @var{may_require_tmp} is true, the library might additionally create a
3646 temporary variable, unless additional checks show that this is not required
3647 (e.g. because walking backward is possible or because both arrays are
3648 contiguous and @code{memmove} takes care of overlap issues).
3650 Note that the assignment of a scalar to an array is permitted. In addition,
3651 the library has to handle numeric-type conversion and for strings, padding
3652 and different character kinds.
3656 @node _gfortran_caf_get
3657 @subsection @code{_gfortran_caf_get} --- Getting data from a remote image
3658 @cindex Coarray, _gfortran_caf_get
3661 @item @emph{Description}:
3662 Called to get an array section or whole array from a a remote,
3663 image identified by the image_index.
3665 @item @emph{Syntax}:
3666 @code{void _gfortran_caf_get_desc (caf_token_t token, size_t offset,
3667 int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector,
3668 gfc_descriptor_t *dest, int src_kind, int dst_kind, bool may_require_tmp)}
3670 @item @emph{Arguments}:
3671 @multitable @columnfractions .15 .70
3672 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3673 @item @var{offset} @tab By which amount of bytes the actual data is shifted
3674 compared to the base address of the coarray.
3675 @item @var{image_index} @tab The ID of the remote image; must be a positive
3677 @item @var{dest} @tab intent(in) Array descriptor of the local array to be
3678 transferred to the remote image
3679 @item @var{src} @tab intent(in) Array descriptor for the remote image for the
3680 bounds and the size. The base_addr shall not be accessed.
3681 @item @var{src_vector} @tab intent(int) If not NULL, it contains the vector
3682 subscript of the destination array; the values are relative to the dimension
3683 triplet of the dest argument.
3684 @item @var{dst_kind} @tab Kind of the destination argument
3685 @item @var{src_kind} @tab Kind of the source argument
3686 @item @var{may_require_tmp} @tab The variable is false it is known at compile
3687 time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
3688 or partially) such that walking @var{src} and @var{dest} in element wise
3689 element order (honoring the stride value) will not lead to wrong results.
3690 Otherwise, the value is true.
3694 It is permitted to have image_id equal the current image; the memory of the
3695 send-to and the send-from might (partially) overlap in that case. The
3696 implementation has to take care that it handles this case, e.g. using
3697 @code{memmove} which handles (partially) overlapping memory. If
3698 @var{may_require_tmp} is true, the library might additionally create a
3699 temporary variable, unless additional checks show that this is not required
3700 (e.g. because walking backward is possible or because both arrays are
3701 contiguous and @code{memmove} takes care of overlap issues).
3703 Note that the library has to handle numeric-type conversion and for strings,
3704 padding and different character kinds.
3708 @node _gfortran_caf_sendget
3709 @subsection @code{_gfortran_caf_sendget} --- Sending data between remote images
3710 @cindex Coarray, _gfortran_caf_sendget
3713 @item @emph{Description}:
3714 Called to send a scalar, an array section or whole array from a remote image
3715 identified by the src_image_index to a remote image identified by the
3718 @item @emph{Syntax}:
3719 @code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset,
3720 int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
3721 caf_token_t src_token, size_t src_offset, int src_image_index,
3722 gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind,
3723 bool may_require_tmp)}
3725 @item @emph{Arguments}:
3726 @multitable @columnfractions .15 .70
3727 @item @var{dst_token} @tab intent(in) An opaque pointer identifying the
3728 destination coarray.
3729 @item @var{dst_offset} @tab By which amount of bytes the actual data is
3730 shifted compared to the base address of the destination coarray.
3731 @item @var{dst_image_index} @tab The ID of the destination remote image; must
3732 be a positive number.
3733 @item @var{dest} @tab intent(in) Array descriptor for the destination
3734 remote image for the bounds and the size. The base_addr shall not be accessed.
3735 @item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
3736 subscript of the destination array; the values are relative to the dimension
3737 triplet of the dest argument.
3738 @item @var{src_token} @tab An opaque pointer identifying the source coarray.
3739 @item @var{src_offset} @tab By which amount of bytes the actual data is shifted
3740 compared to the base address of the source coarray.
3741 @item @var{src_image_index} @tab The ID of the source remote image; must be a
3743 @item @var{src} @tab intent(in) Array descriptor of the local array to be
3744 transferred to the remote image.
3745 @item @var{src_vector} @tab intent(in) Array descriptor of the local array to
3746 be transferred to the remote image
3747 @item @var{dst_kind} @tab Kind of the destination argument
3748 @item @var{src_kind} @tab Kind of the source argument
3749 @item @var{may_require_tmp} @tab The variable is false it is known at compile
3750 time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
3751 or partially) such that walking @var{src} and @var{dest} in element wise
3752 element order (honoring the stride value) will not lead to wrong results.
3753 Otherwise, the value is true.
3757 It is permitted to have image_ids equal; the memory of the send-to and the
3758 send-from might (partially) overlap in that case. The implementation has to
3759 take care that it handles this case, e.g. using @code{memmove} which handles
3760 (partially) overlapping memory. If @var{may_require_tmp} is true, the library
3761 might additionally create a temporary variable, unless additional checks show
3762 that this is not required (e.g. because walking backward is possible or because
3763 both arrays are contiguous and @code{memmove} takes care of overlap issues).
3765 Note that the assignment of a scalar to an array is permitted. In addition,
3766 the library has to handle numeric-type conversion and for strings, padding and
3767 different character kinds.
3771 @node _gfortran_caf_lock
3772 @subsection @code{_gfortran_caf_lock} --- Locking a lock variable
3773 @cindex Coarray, _gfortran_caf_lock
3776 @item @emph{Description}:
3777 Acquire a lock on the given image on a scalar locking variable or for the
3778 given array element for an array-valued variable. If the @var{aquired_lock}
3779 is @code{NULL}, the function return after having obtained the lock. If it is
3780 nonnull, the result is is assigned the value true (one) when the lock could be
3781 obtained and false (zero) otherwise. Locking a lock variable which has already
3782 been locked by the same image is an error.
3784 @item @emph{Syntax}:
3785 @code{void _gfortran_caf_lock (caf_token_t token, size_t index, int image_index,
3786 int *aquired_lock, int *stat, char *errmsg, int errmsg_len)}
3788 @item @emph{Arguments}:
3789 @multitable @columnfractions .15 .70
3790 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3791 @item @var{index} @tab Array index; first array index is 0. For scalars, it is
3793 @item @var{image_index} @tab The ID of the remote image; must be a positive
3795 @item @var{aquired_lock} @tab intent(out) If not NULL, it returns whether lock
3797 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
3798 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3799 an error message; may be NULL
3800 @item @var{errmsg_len} @tab the buffer size of errmsg.
3804 This function is also called for critical blocks; for those, the array index
3805 is always zero and the image index is one. Libraries are permitted to use other
3806 images for critical-block locking variables.
3809 @node _gfortran_caf_unlock
3810 @subsection @code{_gfortran_caf_lock} --- Unlocking a lock variable
3811 @cindex Coarray, _gfortran_caf_unlock
3814 @item @emph{Description}:
3815 Release a lock on the given image on a scalar locking variable or for the
3816 given array element for an array-valued variable. Unlocking a lock variable
3817 which is unlocked or has been locked by a different image is an error.
3819 @item @emph{Syntax}:
3820 @code{void _gfortran_caf_unlock (caf_token_t token, size_t index, int image_index,
3821 int *stat, char *errmsg, int errmsg_len)}
3823 @item @emph{Arguments}:
3824 @multitable @columnfractions .15 .70
3825 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3826 @item @var{index} @tab Array index; first array index is 0. For scalars, it is
3828 @item @var{image_index} @tab The ID of the remote image; must be a positive
3830 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
3832 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3833 an error message; may be NULL
3834 @item @var{errmsg_len} @tab the buffer size of errmsg.
3838 This function is also called for critical block; for those, the array index
3839 is always zero and the image index is one. Libraries are permitted to use other
3840 images for critical-block locking variables.
3843 @node _gfortran_caf_event_post
3844 @subsection @code{_gfortran_caf_event_post} --- Post an event
3845 @cindex Coarray, _gfortran_caf_event_post
3848 @item @emph{Description}:
3849 Increment the event count of the specified event variable.
3851 @item @emph{Syntax}:
3852 @code{void _gfortran_caf_event_post (caf_token_t token, size_t index,
3853 int image_index, int *stat, char *errmsg, int errmsg_len)}
3855 @item @emph{Arguments}:
3856 @multitable @columnfractions .15 .70
3857 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3858 @item @var{index} @tab Array index; first array index is 0. For scalars, it is
3860 @item @var{image_index} @tab The ID of the remote image; must be a positive
3861 number; zero indicates the current image when accessed noncoindexed.
3862 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
3863 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3864 an error message; may be NULL
3865 @item @var{errmsg_len} @tab the buffer size of errmsg.
3869 This acts like an atomic add of one to the remote image's event variable.
3870 The statement is an image-control statement but does not imply sync memory.
3871 Still, all preceeding push communications of this image to the specified
3872 remote image has to be completed before @code{event_wait} on the remote
3878 @node _gfortran_caf_event_wait
3879 @subsection @code{_gfortran_caf_event_wait} --- Wait that an event occurred
3880 @cindex Coarray, _gfortran_caf_event_wait
3883 @item @emph{Description}:
3884 Wait until the event count has reached at least the specified
3885 @var{until_count}; if so, atomically decrement the event variable by this
3888 @item @emph{Syntax}:
3889 @code{void _gfortran_caf_event_wait (caf_token_t token, size_t index,
3890 int until_count, int *stat, char *errmsg, int errmsg_len)}
3892 @item @emph{Arguments}:
3893 @multitable @columnfractions .15 .70
3894 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3895 @item @var{index} @tab Array index; first array index is 0. For scalars, it is
3897 @item @var{until_count} @tab The number of events which have to be available
3898 before the function returns.
3899 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
3900 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3901 an error message; may be NULL
3902 @item @var{errmsg_len} @tab the buffer size of errmsg.
3906 This function only operates on a local coarray. It acts like a loop checking
3907 atomically the value of the event variable, breaking if the value is greater
3908 or equal the requested number of counts. Before the function returns, the
3909 event variable has to be decremented by the requested @var{until_count} value.
3910 A possible implementation would be a busy loop for a certain number of spins
3911 (possibly depending on the number of threads relative to the number of available
3912 cores) followed by other waiting strategy such as a sleeping wait (possibly with
3913 an increasing number of sleep time) or, if possible, a futex wait.
3915 The statement is an image-control statement but does not imply sync memory.
3916 Still, all preceeding push communications to this image of images having
3917 issued a @code{event_push} have to be completed before this function returns.
3922 @node _gfortran_caf_event_query
3923 @subsection @code{_gfortran_caf_event_query} --- Query event count
3924 @cindex Coarray, _gfortran_caf_event_query
3927 @item @emph{Description}:
3928 Return the event count of the specified event count.
3930 @item @emph{Syntax}:
3931 @code{void _gfortran_caf_event_query (caf_token_t token, size_t index,
3932 int image_index, int *count, int *stat)}
3934 @item @emph{Arguments}:
3935 @multitable @columnfractions .15 .70
3936 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3937 @item @var{index} @tab Array index; first array index is 0. For scalars, it is
3939 @item @var{image_index} @tab The ID of the remote image; must be a positive
3940 number; zero indicates the current image when accessed noncoindexed.
3941 @item @var{count} @tab intent(out) The number of events currently posted to
3943 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
3947 The typical use is to check the local even variable to only call
3948 @code{event_wait} when the data is available. However, a coindexed variable
3949 is permitted; there is no ordering or synchronization implied. It acts like
3950 an atomic fetch of the value of the event variable.
3953 @node _gfortran_caf_sync_all
3954 @subsection @code{_gfortran_caf_sync_all} --- All-image barrier
3955 @cindex Coarray, _gfortran_caf_sync_all
3958 @item @emph{Description}:
3959 Synchronization of all images in the current team; the program only continues
3960 on a given image after this function has been called on all images of the
3961 current team. Additionally, it ensures that all pending data transfers of
3962 previous segment have completed.
3964 @item @emph{Syntax}:
3965 @code{void _gfortran_caf_sync_all (int *stat, char *errmsg, int errmsg_len)}
3967 @item @emph{Arguments}:
3968 @multitable @columnfractions .15 .70
3969 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
3970 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3971 an error message; may be NULL
3972 @item @var{errmsg_len} @tab the buffer size of errmsg.
3978 @node _gfortran_caf_sync_images
3979 @subsection @code{_gfortran_caf_sync_images} --- Barrier for selected images
3980 @cindex Coarray, _gfortran_caf_sync_images
3983 @item @emph{Description}:
3984 Synchronization between the specified images; the program only continues on a
3985 given image after this function has been called on all images specified for
3986 that image. Note that one image can wait for all other images in the current
3987 team (e.g. via @code{sync images(*)}) while those only wait for that specific
3988 image. Additionally, @code{sync images} it ensures that all pending data
3989 transfers of previous segment have completed.
3991 @item @emph{Syntax}:
3992 @code{void _gfortran_caf_sync_images (int count, int images[], int *stat,
3993 char *errmsg, int errmsg_len)}
3995 @item @emph{Arguments}:
3996 @multitable @columnfractions .15 .70
3997 @item @var{count} @tab the number of images which are provided in the next
3998 argument. For a zero-sized array, the value is zero. For @code{sync
3999 images (*)}, the value is @math{-1}.
4000 @item @var{images} @tab intent(in) an array with the images provided by the
4001 user. If @var{count} is zero, a NULL pointer is passed.
4002 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4003 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4004 an error message; may be NULL
4005 @item @var{errmsg_len} @tab the buffer size of errmsg.
4011 @node _gfortran_caf_sync_memory
4012 @subsection @code{_gfortran_caf_sync_memory} --- Wait for completion of segment-memory operations
4013 @cindex Coarray, _gfortran_caf_sync_memory
4016 @item @emph{Description}:
4017 Acts as optimization barrier between different segments. It also ensures that
4018 all pending memory operations of this image have been completed.
4020 @item @emph{Syntax}:
4021 @code{void _gfortran_caf_sync_memory (int *stat, char *errmsg, int errmsg_len)}
4023 @item @emph{Arguments}:
4024 @multitable @columnfractions .15 .70
4025 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4026 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4027 an error message; may be NULL
4028 @item @var{errmsg_len} @tab the buffer size of errmsg.
4031 @item @emph{NOTE} A simple implementation could be
4032 @code{__asm__ __volatile__ ("":::"memory")} to prevent code movements.
4037 @node _gfortran_caf_error_stop
4038 @subsection @code{_gfortran_caf_error_stop} --- Error termination with exit code
4039 @cindex Coarray, _gfortran_caf_error_stop
4042 @item @emph{Description}:
4043 Invoked for an @code{ERROR STOP} statement which has an integer argument. The
4044 function should terminate the program with the specified exit code.
4047 @item @emph{Syntax}:
4048 @code{void _gfortran_caf_error_stop (int32_t error)}
4050 @item @emph{Arguments}:
4051 @multitable @columnfractions .15 .70
4052 @item @var{error} @tab the exit status to be used.
4058 @node _gfortran_caf_error_stop_str
4059 @subsection @code{_gfortran_caf_error_stop_str} --- Error termination with string
4060 @cindex Coarray, _gfortran_caf_error_stop_str
4063 @item @emph{Description}:
4064 Invoked for an @code{ERROR STOP} statement which has a string as argument. The
4065 function should terminate the program with a nonzero-exit code.
4067 @item @emph{Syntax}:
4068 @code{void _gfortran_caf_error_stop (const char *string, int32_t len)}
4070 @item @emph{Arguments}:
4071 @multitable @columnfractions .15 .70
4072 @item @var{string} @tab the error message (not zero terminated)
4073 @item @var{len} @tab the length of the string
4079 @node _gfortran_caf_atomic_define
4080 @subsection @code{_gfortran_caf_atomic_define} --- Atomic variable assignment
4081 @cindex Coarray, _gfortran_caf_atomic_define
4084 @item @emph{Description}:
4085 Assign atomically a value to an integer or logical variable.
4087 @item @emph{Syntax}:
4088 @code{void _gfortran_caf_atomic_define (caf_token_t token, size_t offset,
4089 int image_index, void *value, int *stat, int type, int kind)}
4091 @item @emph{Arguments}:
4092 @multitable @columnfractions .15 .70
4093 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4094 @item @var{offset} @tab By which amount of bytes the actual data is shifted
4095 compared to the base address of the coarray.
4096 @item @var{image_index} @tab The ID of the remote image; must be a positive
4097 number; zero indicates the current image when used noncoindexed.
4098 @item @var{value} @tab intent(in) the value to be assigned, passed by reference.
4099 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4100 @item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
4101 @code{BT_LOGICAL} (2).
4102 @item @var{kind} @tab The kind value (only 4; always @code{int})
4108 @node _gfortran_caf_atomic_ref
4109 @subsection @code{_gfortran_caf_atomic_ref} --- Atomic variable reference
4110 @cindex Coarray, _gfortran_caf_atomic_ref
4113 @item @emph{Description}:
4114 Reference atomically a value of a kind-4 integer or logical variable.
4116 @item @emph{Syntax}:
4117 @code{void _gfortran_caf_atomic_ref (caf_token_t token, size_t offset,
4118 int image_index, void *value, int *stat, int type, int kind)}
4120 @item @emph{Arguments}:
4121 @item @emph{Arguments}:
4122 @multitable @columnfractions .15 .70
4123 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4124 @item @var{offset} @tab By which amount of bytes the actual data is shifted
4125 compared to the base address of the coarray.
4126 @item @var{image_index} @tab The ID of the remote image; must be a positive
4127 number; zero indicates the current image when used noncoindexed.
4128 @item @var{value} @tab intent(out) The variable assigned the atomically
4129 referenced variable.
4130 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4131 @item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
4132 @code{BT_LOGICAL} (2).
4133 @item @var{kind} @tab The kind value (only 4; always @code{int})
4139 @node _gfortran_caf_atomic_cas
4140 @subsection @code{_gfortran_caf_atomic_cas} --- Atomic compare and swap
4141 @cindex Coarray, _gfortran_caf_atomic_cas
4144 @item @emph{Description}:
4145 Atomic compare and swap of a kind-4 integer or logical variable. Assigns
4146 atomically the specified value to the atomic variable, if the latter has
4147 the value specified by the passed condition value.
4149 @item @emph{Syntax}:
4150 @code{void _gfortran_caf_atomic_cas (caf_token_t token, size_t offset,
4151 int image_index, void *old, void *compare, void *new_val, int *stat,
4152 int type, int kind)}
4154 @item @emph{Arguments}:
4155 @multitable @columnfractions .15 .70
4156 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4157 @item @var{offset} @tab By which amount of bytes the actual data is shifted
4158 compared to the base address of the coarray.
4159 @item @var{image_index} @tab The ID of the remote image; must be a positive
4160 number; zero indicates the current image when used noncoindexed.
4161 @item @var{old} @tab intent(out) the value which the atomic variable had
4162 just before the cas operation.
4163 @item @var{compare} @tab intent(in) The value used for comparision.
4164 @item @var{new_val} @tab intent(in) The new value for the atomic variable,
4165 assigned to the atomic variable, if @code{compare} equals the value of the
4167 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4168 @item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
4169 @code{BT_LOGICAL} (2).
4170 @item @var{kind} @tab The kind value (only 4; always @code{int})
4176 @node _gfortran_caf_atomic_op
4177 @subsection @code{_gfortran_caf_atomic_op} --- Atomic operation
4178 @cindex Coarray, _gfortran_caf_atomic_op
4181 @item @emph{Description}:
4182 Apply an operation atomically to an atomic integer or logical variable.
4183 After the operation, @var{old} contains the value just before the operation,
4184 which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the @code{value} to
4185 the atomic integer variable or does a bitwise AND, OR or exclusive OR of the
4186 between the atomic variable and @var{value}; the result is then stored in the
4189 @item @emph{Syntax}:
4190 @code{void _gfortran_caf_atomic_op (int op, caf_token_t token, size_t offset,
4191 int image_index, void *value, void *old, int *stat, int type, int kind)}
4193 @item @emph{Arguments}:
4194 @multitable @columnfractions .15 .70
4195 @item @var{op} @tab the operation to be performed; possible values
4196 @code{GFC_CAF_ATOMIC_ADD} (1), @code{GFC_CAF_ATOMIC_AND} (2),
4197 @code{GFC_CAF_ATOMIC_OR} (3), @code{GFC_CAF_ATOMIC_XOR} (4).
4198 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4199 @item @var{offset} @tab By which amount of bytes the actual data is shifted
4200 compared to the base address of the coarray.
4201 @item @var{image_index} @tab The ID of the remote image; must be a positive
4202 number; zero indicates the current image when used noncoindexed.
4203 @item @var{old} @tab intent(out) the value which the atomic variable had
4204 just before the atomic operation.
4205 @item @var{val} @tab intent(in) The new value for the atomic variable,
4206 assigned to the atomic variable, if @code{compare} equals the value of the
4208 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4209 @item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
4210 @code{BT_LOGICAL} (2).
4211 @item @var{kind} @tab The kind value (only 4; always @code{int})
4218 @node _gfortran_caf_co_broadcast
4219 @subsection @code{_gfortran_caf_co_broadcast} --- Sending data to all images
4220 @cindex Coarray, _gfortran_caf_co_broadcast
4223 @item @emph{Description}:
4224 Distribute a value from a given image to all other images in the team. Has to
4225 be called collectively.
4227 @item @emph{Syntax}:
4228 @code{void _gfortran_caf_co_broadcast (gfc_descriptor_t *a,
4229 int source_image, int *stat, char *errmsg, int errmsg_len)}
4231 @item @emph{Arguments}:
4232 @multitable @columnfractions .15 .70
4233 @item @var{a} @tab intent(inout) And array descriptor with the data to be
4234 breoadcasted (on @var{source_image}) or to be received (other images).
4235 @item @var{source_image} @tab The ID of the image from which the data should
4237 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4238 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4239 an error message; may be NULL
4240 @item @var{errmsg_len} @tab the buffer size of errmsg.
4246 @node _gfortran_caf_co_max
4247 @subsection @code{_gfortran_caf_co_max} --- Collective maximum reduction
4248 @cindex Coarray, _gfortran_caf_co_max
4251 @item @emph{Description}:
4252 Calculates the for the each array element of the variable @var{a} the maximum
4253 value for that element in the current team; if @var{result_image} has the
4254 value 0, the result shall be stored on all images, otherwise, only on the
4255 specified image. This function operates on numeric values and character
4258 @item @emph{Syntax}:
4259 @code{void _gfortran_caf_co_max (gfc_descriptor_t *a, int result_image,
4260 int *stat, char *errmsg, int a_len, int errmsg_len)}
4262 @item @emph{Arguments}:
4263 @multitable @columnfractions .15 .70
4264 @item @var{a} @tab intent(inout) And array descriptor with the data to be
4265 breoadcasted (on @var{source_image}) or to be received (other images).
4266 @item @var{result_image} @tab The ID of the image to which the reduced
4267 value should be copied to; if zero, it has to be copied to all images.
4268 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4269 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4270 an error message; may be NULL
4271 @item @var{a_len} @tab The string length of argument @var{a}.
4272 @item @var{errmsg_len} @tab the buffer size of errmsg.
4276 If @var{result_image} is nonzero, the value on all images except of the
4277 specified one become undefined; hence, the library may make use of this.
4282 @node _gfortran_caf_co_min
4283 @subsection @code{_gfortran_caf_co_min} --- Collective minimum reduction
4284 @cindex Coarray, _gfortran_caf_co_min
4287 @item @emph{Description}:
4288 Calculates the for the each array element of the variable @var{a} the minimum
4289 value for that element in the current team; if @var{result_image} has the
4290 value 0, the result shall be stored on all images, otherwise, only on the
4291 specified image. This function operates on numeric values and character
4294 @item @emph{Syntax}:
4295 @code{void _gfortran_caf_co_min (gfc_descriptor_t *a, int result_image,
4296 int *stat, char *errmsg, int a_len, int errmsg_len)}
4298 @item @emph{Arguments}:
4299 @multitable @columnfractions .15 .70
4300 @item @var{a} @tab intent(inout) And array descriptor with the data to be
4301 breoadcasted (on @var{source_image}) or to be received (other images).
4302 @item @var{result_image} @tab The ID of the image to which the reduced
4303 value should be copied to; if zero, it has to be copied to all images.
4304 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4305 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4306 an error message; may be NULL
4307 @item @var{a_len} @tab The string length of argument @var{a}.
4308 @item @var{errmsg_len} @tab the buffer size of errmsg.
4312 If @var{result_image} is nonzero, the value on all images except of the
4313 specified one become undefined; hence, the library may make use of this.
4318 @node _gfortran_caf_co_sum
4319 @subsection @code{_gfortran_caf_co_sum} --- Collective summing reduction
4320 @cindex Coarray, _gfortran_caf_co_sum
4323 @item @emph{Description}:
4324 Calculates the for the each array element of the variable @var{a} the sum
4325 value for that element in the current team; if @var{result_image} has the
4326 value 0, the result shall be stored on all images, otherwise, only on the
4327 specified image. This function operates on numeric values.
4329 @item @emph{Syntax}:
4330 @code{void _gfortran_caf_co_sum (gfc_descriptor_t *a, int result_image,
4331 int *stat, char *errmsg, int errmsg_len)}
4333 @item @emph{Arguments}:
4334 @multitable @columnfractions .15 .70
4335 @item @var{a} @tab intent(inout) And array descriptor with the data to be
4336 breoadcasted (on @var{source_image}) or to be received (other images).
4337 @item @var{result_image} @tab The ID of the image to which the reduced
4338 value should be copied to; if zero, it has to be copied to all images.
4339 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4340 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4341 an error message; may be NULL
4342 @item @var{errmsg_len} @tab the buffer size of errmsg.
4346 If @var{result_image} is nonzero, the value on all images except of the
4347 specified one become undefined; hence, the library may make use of this.
4352 @node _gfortran_caf_co_reduce
4353 @subsection @code{_gfortran_caf_co_reduce} --- Generic collective reduction
4354 @cindex Coarray, _gfortran_caf_co_reduce
4357 @item @emph{Description}:
4358 Calculates the for the each array element of the variable @var{a} the reduction
4359 value for that element in the current team; if @var{result_image} has the
4360 value 0, the result shall be stored on all images, otherwise, only on the
4361 specified image. The @var{opr} is a pure function doing a mathematically
4362 commutative and associative operation.
4364 The @var{opr_flags} denote the following; the values are bitwise ored.
4365 @code{GFC_CAF_BYREF} (1) if the result should be returned
4366 by value; @code{GFC_CAF_HIDDENLEN} (2) whether the result and argument
4367 string lengths shall be specified as hidden argument;
4368 @code{GFC_CAF_ARG_VALUE} (4) whether the arguments shall be passed by value,
4369 @code{GFC_CAF_ARG_DESC} (8) whether the arguments shall be passed by descriptor.
4372 @item @emph{Syntax}:
4373 @code{void _gfortran_caf_co_reduce (gfc_descriptor_t *a,
4374 void * (*opr) (void *, void *), int opr_flags, int result_image,
4375 int *stat, char *errmsg, int a_len, int errmsg_len)}
4377 @item @emph{Arguments}:
4378 @multitable @columnfractions .15 .70
4379 @item @var{opr} @tab Function pointer to the reduction function.
4380 @item @var{opr_flags} @tab Flags regarding the reduction function
4381 @item @var{a} @tab intent(inout) And array descriptor with the data to be
4382 breoadcasted (on @var{source_image}) or to be received (other images).
4383 @item @var{result_image} @tab The ID of the image to which the reduced
4384 value should be copied to; if zero, it has to be copied to all images.
4385 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4386 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4387 an error message; may be NULL
4388 @item @var{a_len} @tab The string length of argument @var{a}.
4389 @item @var{errmsg_len} @tab the buffer size of errmsg.
4393 If @var{result_image} is nonzero, the value on all images except of the
4394 specified one become undefined; hence, the library may make use of this.
4395 For character arguments, the result is passed as first argument, followed
4396 by the result string length, next come the two string arguments, followed
4397 by the two hidden arguments. With C binding, there are no hidden arguments
4398 and by-reference passing and either only a single character is passed or
4399 an array descriptor.
4403 @c Intrinsic Procedures
4404 @c ---------------------------------------------------------------------
4406 @include intrinsic.texi
4413 @c ---------------------------------------------------------------------
4415 @c ---------------------------------------------------------------------
4418 @unnumbered Contributing
4419 @cindex Contributing
4421 Free software is only possible if people contribute to efforts
4423 We're always in need of more people helping out with ideas
4424 and comments, writing documentation and contributing code.
4426 If you want to contribute to GNU Fortran,
4427 have a look at the long lists of projects you can take on.
4428 Some of these projects are small,
4429 some of them are large;
4430 some are completely orthogonal to the rest of what is
4431 happening on GNU Fortran,
4432 but others are ``mainstream'' projects in need of enthusiastic hackers.
4433 All of these projects are important!
4434 We will eventually get around to the things here,
4435 but they are also things doable by someone who is willing and able.
4440 * Proposed Extensions::
4445 @section Contributors to GNU Fortran
4446 @cindex Contributors
4450 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
4451 also the initiator of the whole project. Thanks Andy!
4452 Most of the interface with GCC was written by @emph{Paul Brook}.
4454 The following individuals have contributed code and/or
4455 ideas and significant help to the GNU Fortran project
4456 (in alphabetical order):
4459 @item Janne Blomqvist
4460 @item Steven Bosscher
4463 @item Fran@,{c}ois-Xavier Coudert
4467 @item Bernhard Fischer
4469 @item Richard Guenther
4470 @item Richard Henderson
4471 @item Katherine Holcomb
4473 @item Niels Kristian Bech Jensen
4474 @item Steven Johnson
4475 @item Steven G. Kargl
4483 @item Christopher D. Rickett
4484 @item Richard Sandiford
4485 @item Tobias Schl@"uter
4494 The following people have contributed bug reports,
4495 smaller or larger patches,
4496 and much needed feedback and encouragement for the
4497 GNU Fortran project:
4501 @item Dominique d'Humi@`eres
4503 @item Erik Schnetter
4504 @item Joost VandeVondele
4507 Many other individuals have helped debug,
4508 test and improve the GNU Fortran compiler over the past few years,
4509 and we welcome you to do the same!
4510 If you already have done so,
4511 and you would like to see your name listed in the
4512 list above, please contact us.
4520 @item Help build the test suite
4521 Solicit more code for donation to the test suite: the more extensive the
4522 testsuite, the smaller the risk of breaking things in the future! We can
4523 keep code private on request.
4525 @item Bug hunting/squishing
4526 Find bugs and write more test cases! Test cases are especially very
4527 welcome, because it allows us to concentrate on fixing bugs instead of
4528 isolating them. Going through the bugzilla database at
4529 @url{https://gcc.gnu.org/@/bugzilla/} to reduce testcases posted there and
4530 add more information (for example, for which version does the testcase
4531 work, for which versions does it fail?) is also very helpful.
4536 @node Proposed Extensions
4537 @section Proposed Extensions
4539 Here's a list of proposed extensions for the GNU Fortran compiler, in no particular
4540 order. Most of these are necessary to be fully compatible with
4541 existing Fortran compilers, but they are not part of the official
4542 J3 Fortran 95 standard.
4544 @subsection Compiler extensions:
4547 User-specified alignment rules for structures.
4550 Automatically extend single precision constants to double.
4553 Compile code that conserves memory by dynamically allocating common and
4554 module storage either on stack or heap.
4557 Compile flag to generate code for array conformance checking (suggest -CC).
4560 User control of symbol names (underscores, etc).
4563 Compile setting for maximum size of stack frame size before spilling
4564 parts to static or heap.
4567 Flag to force local variables into static space.
4570 Flag to force local variables onto stack.
4574 @subsection Environment Options
4577 Pluggable library modules for random numbers, linear algebra.
4578 LA should use BLAS calling conventions.
4581 Environment variables controlling actions on arithmetic exceptions like
4582 overflow, underflow, precision loss---Generate NaN, abort, default.
4586 Set precision for fp units that support it (i387).
4589 Variable for setting fp rounding mode.
4592 Variable to fill uninitialized variables with a user-defined bit
4596 Environment variable controlling filename that is opened for that unit
4600 Environment variable to clear/trash memory being freed.
4603 Environment variable to control tracing of allocations and frees.
4606 Environment variable to display allocated memory at normal program end.
4609 Environment variable for filename for * IO-unit.
4612 Environment variable for temporary file directory.
4615 Environment variable forcing standard output to be line buffered (Unix).
4620 @c ---------------------------------------------------------------------
4621 @c GNU General Public License
4622 @c ---------------------------------------------------------------------
4624 @include gpl_v3.texi
4628 @c ---------------------------------------------------------------------
4629 @c GNU Free Documentation License
4630 @c ---------------------------------------------------------------------
4636 @c ---------------------------------------------------------------------
4637 @c Funding Free Software
4638 @c ---------------------------------------------------------------------
4640 @include funding.texi
4642 @c ---------------------------------------------------------------------
4644 @c ---------------------------------------------------------------------
4647 @unnumbered Option Index
4648 @command{gfortran}'s command line options are indexed here without any
4649 initial @samp{-} or @samp{--}. Where an option has both positive and
4650 negative forms (such as -foption and -fno-option), relevant entries in
4651 the manual are indexed under the most appropriate form; it may sometimes
4652 be useful to look up both forms.
4656 @unnumbered Keyword Index