1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set copyrights-gfortran 1999-2024
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 * Compiler Characteristics:: User-visible implementation details.
184 * Extensions:: Language extensions implemented by GNU Fortran.
185 * Mixed-Language Programming:: Interoperability with C
186 * Coarray Programming::
187 * Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran.
188 * Intrinsic Modules:: Intrinsic modules supported by GNU Fortran.
190 * Contributing:: How you can help.
191 * Copying:: GNU General Public License says
192 how you can copy and share GNU Fortran.
193 * GNU Free Documentation License::
194 How you can copy and share this manual.
195 * Funding:: How to help assure continued work for free software.
196 * Option Index:: Index of command line options
197 * Keyword Index:: Index of concepts
201 @c ---------------------------------------------------------------------
203 @c ---------------------------------------------------------------------
206 @chapter Introduction
208 @c The following duplicates the text on the TexInfo table of contents.
210 This manual documents the use of @command{gfortran}, the GNU Fortran
211 compiler. You can find in this manual how to invoke @command{gfortran},
212 as well as its features and incompatibilities.
215 @emph{Warning:} This document, and the compiler it describes, are still
216 under development. While efforts are made to keep it up-to-date, it
217 might not accurately reflect the status of the most recent GNU Fortran
223 * About GNU Fortran:: What you should know about the GNU Fortran compiler.
224 * GNU Fortran and GCC:: You can compile Fortran, C, or other programs.
225 * Standards:: Standards supported by GNU Fortran.
229 @c ---------------------------------------------------------------------
231 @c ---------------------------------------------------------------------
233 @node About GNU Fortran
234 @section About GNU Fortran
236 The GNU Fortran compiler is the successor to @command{g77}, the
237 Fortran 77 front end included in GCC prior to version 4 (released in
238 2005). While it is backward-compatible with most @command{g77}
239 extensions and command-line options, @command{gfortran} is a completely new
240 implemention designed to support more modern dialects of Fortran.
241 GNU Fortran implements the Fortran 77, 90 and 95 standards
242 completely, most of the Fortran 2003 and 2008 standards, and some
243 features from the 2018 standard. It also implements several extensions
244 including OpenMP and OpenACC support for parallel programming.
246 The GNU Fortran compiler passes the
247 @uref{http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html,
248 NIST Fortran 77 Test Suite}, and produces acceptable results on the
249 @uref{https://www.netlib.org/lapack/faq.html, LAPACK Test Suite}.
250 It also provides respectable performance on
251 the @uref{https://polyhedron.com/?page_id=175,
252 Polyhedron Fortran compiler benchmarks} and the
253 @uref{https://www.netlib.org/benchmark/livermore,
254 Livermore Fortran Kernels test}. It has been used to compile a number of
255 large real-world programs, including
256 @uref{http://hirlam.org/, the HARMONIE and HIRLAM weather forecasting code} and
257 @uref{https://github.com/dylan-jayatilaka/tonto,
258 the Tonto quantum chemistry package}; see
259 @url{https://gcc.gnu.org/@/wiki/@/GfortranApps} for an extended list.
261 GNU Fortran provides the following functionality:
265 Read a program, stored in a file and containing @dfn{source code}
266 instructions written in Fortran 77.
269 Translate the program into instructions a computer
270 can carry out more quickly than it takes to translate the
271 original Fortran instructions.
272 The result after compilation of a program is
274 which is efficiently translated and processed
275 by a machine such as your computer.
276 Humans usually are not as good writing machine code
277 as they are at writing Fortran (or C++, Ada, or Java),
278 because it is easy to make tiny mistakes writing machine code.
281 Provide information about the reasons why
282 the compiler may be unable to create a binary from the source code,
283 for example if the source code is flawed.
284 The Fortran language standards require that the compiler can point out
285 mistakes in your code.
286 An incorrect usage of the language causes an @dfn{error message}.
288 The compiler also attempts to diagnose cases where your
289 program contains a correct usage of the language,
290 but instructs the computer to do something questionable.
291 This kind of diagnostic message is called a @dfn{warning message}.
294 Provide optional information about the translation passes
295 from the source code to machine code.
296 This can help you to find the cause of
297 certain bugs which may not be obvious in the source code,
298 but may be more easily found at a lower level compiler output.
299 It also helps developers to find bugs in the compiler itself.
302 Provide information in the generated machine code that can
303 make it easier to find bugs in the program (using a debugging tool,
304 called a @dfn{debugger}, such as the GNU Debugger @command{gdb}).
307 Locate and gather machine code already generated to
308 perform actions requested by statements in the program.
309 This machine code is organized into @dfn{modules} and is located
310 and @dfn{linked} to the user program.
313 The GNU Fortran compiler consists of several components:
317 A version of the @command{gcc} command
318 (which also might be installed as the system's @command{cc} command)
319 that also understands and accepts Fortran source code.
320 The @command{gcc} command is the @dfn{driver} program for
321 all the languages in the GNU Compiler Collection (GCC);
323 you can compile the source code of any language for
324 which a front end is available in GCC.
327 The @command{gfortran} command itself,
328 which also might be installed as the
329 system's @command{f95} command.
330 @command{gfortran} is just another driver program,
331 but specifically for the Fortran compiler only.
332 The primary difference between the @command{gcc} and @command{gfortran}
333 commands is that the latter automatically links the correct libraries
337 A collection of run-time libraries.
338 These libraries contain the machine code needed to support
339 capabilities of the Fortran language that are not directly
340 provided by the machine code generated by the
341 @command{gfortran} compilation phase,
342 such as intrinsic functions and subroutines,
343 and routines for interaction with files and the operating system.
344 @c and mechanisms to spawn,
345 @c unleash and pause threads in parallelized code.
348 The Fortran compiler itself, (@command{f951}).
349 This is the GNU Fortran parser and code generator,
350 linked to and interfaced with the GCC backend library.
351 @command{f951} ``translates'' the source code to
352 assembler code. You would typically not use this
354 instead, the @command{gcc} or @command{gfortran} driver
355 programs call it for you.
359 @c ---------------------------------------------------------------------
360 @c GNU Fortran and GCC
361 @c ---------------------------------------------------------------------
363 @node GNU Fortran and GCC
364 @section GNU Fortran and GCC
365 @cindex GNU Compiler Collection
368 GNU Fortran is a part of GCC, the @dfn{GNU Compiler Collection}. GCC
369 consists of a collection of front ends for various languages, which
370 translate the source code into a language-independent form called
371 @dfn{GENERIC}. This is then processed by a common middle end which
372 provides optimization, and then passed to one of a collection of back
373 ends which generate code for different computer architectures and
376 Functionally, this is implemented with a driver program (@command{gcc})
377 which provides the command-line interface for the compiler. It calls
378 the relevant compiler front-end program (e.g., @command{f951} for
379 Fortran) for each file in the source code, and then calls the assembler
380 and linker as appropriate to produce the compiled output. In a copy of
381 GCC that has been compiled with Fortran language support enabled,
382 @command{gcc} recognizes files with @file{.f}, @file{.for}, @file{.ftn},
383 @file{.f90}, @file{.f95}, @file{.f03} and @file{.f08} extensions as
384 Fortran source code, and compiles it accordingly. A @command{gfortran}
385 driver program is also provided, which is identical to @command{gcc}
386 except that it automatically links the Fortran runtime libraries into the
389 Source files with @file{.f}, @file{.for}, @file{.fpp}, @file{.ftn}, @file{.F},
390 @file{.FOR}, @file{.FPP}, and @file{.FTN} extensions are treated as fixed form.
391 Source files with @file{.f90}, @file{.f95}, @file{.f03}, @file{.f08},
392 @file{.F90}, @file{.F95}, @file{.F03} and @file{.F08} extensions are
393 treated as free form. The capitalized versions of either form are run
394 through preprocessing. Source files with the lower case @file{.fpp}
395 extension are also run through preprocessing.
397 This manual specifically documents the Fortran front end, which handles
398 the programming language's syntax and semantics. The aspects of GCC
399 that relate to the optimization passes and the back-end code generation
400 are documented in the GCC manual; see
401 @ref{Top,,Introduction,gcc,Using the GNU Compiler Collection (GCC)}.
402 The two manuals together provide a complete reference for the GNU
405 @c ---------------------------------------------------------------------
407 @c ---------------------------------------------------------------------
414 * Fortran 95 status::
415 * Fortran 2003 status::
416 * Fortran 2008 status::
417 * Fortran 2018 status::
420 Fortran is developed by the Working Group 5 of Sub-Committee 22 of the
421 Joint Technical Committee 1 of the International Organization for
422 Standardization and the International Electrotechnical Commission (IEC).
423 This group is known as @uref{http://www.nag.co.uk/sc22wg5/, WG5}.
424 Official Fortran standard documents are available for purchase
425 from ISO; a collection of free documents (typically final drafts) are
426 also available on the @uref{https://gcc.gnu.org/wiki/GFortranStandards, wiki}.
428 The GNU Fortran compiler implements ISO/IEC 1539:1997 (Fortran 95).
429 As such, it can also compile essentially all standard-compliant
430 Fortran 90 and Fortran 77 programs. It also supports the ISO/IEC
431 TR-15581 enhancements to allocatable arrays.
433 GNU Fortran also supports almost all of ISO/IEC 1539-1:2004
434 (Fortran 2003) and ISO/IEC 1539-1:2010 (Fortran 2008).
435 It has partial support for features introduced in ISO/IEC
436 1539:2018 (Fortran 2018), the most recent version of the Fortran
437 language standard, including full support for the Technical Specification
438 @code{Further Interoperability of Fortran with C} (ISO/IEC TS 29113:2012).
439 More details on support for these standards can be
440 found in the following sections of the documentation.
442 Additionally, the GNU Fortran compilers supports the OpenMP specification
443 (version 4.5 and partial support of the features of the 5.0 version,
444 @url{https://openmp.org/@/specifications/}).
445 There also is support for the OpenACC specification (targeting
446 version 2.6, @uref{https://www.openacc.org/}). See
447 @uref{https://gcc.gnu.org/wiki/OpenACC} for more information.
449 @node Fortran 95 status
450 @subsection Fortran 95 status
451 @cindex Varying length strings
452 @cindex strings, varying length
453 @cindex conditional compilation
455 The Fortran 95 standard specifies in Part 2 (ISO/IEC 1539-2:2000)
456 varying length character strings. While GNU Fortran currently does not
457 support such strings directly, there exist two Fortran implementations
458 for them, which work with GNU Fortran. One can be found at
459 @uref{http://user.astro.wisc.edu/~townsend/static.php?ref=iso-varying-string}.
461 Deferred-length character strings of Fortran 2003 supports part of
462 the features of @code{ISO_VARYING_STRING} and should be considered as
463 replacement. (Namely, allocatable or pointers of the type
464 @code{character(len=:)}.)
466 Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines
467 Conditional Compilation, which is not widely used and not directly
468 supported by the GNU Fortran compiler. You can use the program coco
469 to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}).
471 @node Fortran 2003 status
472 @subsection Fortran 2003 status
474 GNU Fortran implements the Fortran 2003 (ISO/IEC 1539-1:2004) standard
475 except for finalization support, which is incomplete.
477 @uref{https://gcc.gnu.org/wiki/Fortran2003, wiki page} for a full list
478 of new features introduced by Fortran 2003 and their implementation status.
480 @node Fortran 2008 status
481 @subsection Fortran 2008 status
483 The GNU Fortran compiler supports almost all features of Fortran 2008;
484 the @uref{https://gcc.gnu.org/wiki/Fortran2008Status, wiki}
485 has some information about the current implementation status.
486 In particular, the following are not yet supported:
490 @code{DO CONCURRENT} and @code{FORALL} do not recognize a
491 type-spec in the loop header.
494 The change to permit any constant expression in subscripts and
495 nested implied-do limits in a @code{DATA} statement has not been implemented.
499 @node Fortran 2018 status
500 @subsection Fortran 2018 status
502 Fortran 2018 (ISO/IEC 1539:2018) is the most recent version
503 of the Fortran language standard. GNU Fortran implements some of the
504 new features of this standard:
508 All Fortran 2018 features derived from ISO/IEC TS 29113:2012,
509 ``Further Interoperability of Fortran with C'', are supported by GNU Fortran.
510 This includes assumed-type and assumed-rank objects and
511 the @code{SELECT RANK} construct as well as the parts relating to
512 @code{BIND(C)} functions.
513 See also @ref{Further Interoperability of Fortran with C}.
516 GNU Fortran supports a subset of features derived from ISO/IEC TS 18508:2015,
517 ``Additional Parallel Features in Fortran'':
521 The new atomic ADD, CAS, FETCH and ADD/OR/XOR, OR and XOR intrinsics.
524 The @code{CO_MIN} and @code{CO_MAX} and @code{SUM} reduction intrinsics,
525 and the @code{CO_BROADCAST} and @code{CO_REDUCE} intrinsic, except that those
526 do not support polymorphic types or types with allocatable, pointer or
527 polymorphic components.
530 Events (@code{EVENT POST}, @code{EVENT WAIT}, @code{EVENT_QUERY}).
533 Failed images (@code{FAIL IMAGE}, @code{IMAGE_STATUS},
534 @code{FAILED_IMAGES}, @code{STOPPED_IMAGES}).
539 An @code{ERROR STOP} statement is permitted in a @code{PURE}
543 GNU Fortran supports the @code{IMPLICIT NONE} statement with an
544 @code{implicit-none-spec-list}.
547 The behavior of the @code{INQUIRE} statement with the @code{RECL=}
548 specifier now conforms to Fortran 2018.
553 @c =====================================================================
554 @c PART I: INVOCATION REFERENCE
555 @c =====================================================================
558 \part{I}{Invoking GNU Fortran}
561 @c ---------------------------------------------------------------------
563 @c ---------------------------------------------------------------------
568 @c ---------------------------------------------------------------------
570 @c ---------------------------------------------------------------------
573 @chapter Runtime: Influencing runtime behavior with environment variables
574 @cindex environment variable
576 The behavior of the @command{gfortran} can be influenced by
577 environment variables.
579 Malformed environment variables are silently ignored.
582 * TMPDIR:: Directory for scratch files
583 * GFORTRAN_STDIN_UNIT:: Unit number for standard input
584 * GFORTRAN_STDOUT_UNIT:: Unit number for standard output
585 * GFORTRAN_STDERR_UNIT:: Unit number for standard error
586 * GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units
587 * GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units.
588 * GFORTRAN_SHOW_LOCUS:: Show location for runtime errors
589 * GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted
590 * GFORTRAN_LIST_SEPARATOR:: Separator for list output
591 * GFORTRAN_CONVERT_UNIT:: Set conversion for unformatted I/O
592 * GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors
593 * GFORTRAN_FORMATTED_BUFFER_SIZE:: Buffer size for formatted files
594 * GFORTRAN_UNFORMATTED_BUFFER_SIZE:: Buffer size for unformatted files
598 @section @env{TMPDIR}---Directory for scratch files
600 When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to
601 create the file in one of the potential directories by testing each
602 directory in the order below.
606 The environment variable @env{TMPDIR}, if it exists.
609 On the MinGW target, the directory returned by the @code{GetTempPath}
610 function. Alternatively, on the Cygwin target, the @env{TMP} and
611 @env{TEMP} environment variables, if they exist, in that order.
614 The @code{P_tmpdir} macro if it is defined, otherwise the directory
618 @node GFORTRAN_STDIN_UNIT
619 @section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input
621 This environment variable can be used to select the unit number
622 preconnected to standard input. This must be a positive integer.
623 The default value is 5.
625 @node GFORTRAN_STDOUT_UNIT
626 @section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output
628 This environment variable can be used to select the unit number
629 preconnected to standard output. This must be a positive integer.
630 The default value is 6.
632 @node GFORTRAN_STDERR_UNIT
633 @section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error
635 This environment variable can be used to select the unit number
636 preconnected to standard error. This must be a positive integer.
637 The default value is 0.
639 @node GFORTRAN_UNBUFFERED_ALL
640 @section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units
642 This environment variable controls whether all I/O is unbuffered. If
643 the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is
644 unbuffered. This will slow down small sequential reads and writes. If
645 the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered.
648 @node GFORTRAN_UNBUFFERED_PRECONNECTED
649 @section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units
651 The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls
652 whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) is unbuffered. If
653 the first letter is @samp{y}, @samp{Y} or @samp{1}, I/O is unbuffered. This
654 will slow down small sequential reads and writes. If the first letter
655 is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. This is the default.
657 @node GFORTRAN_SHOW_LOCUS
658 @section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors
660 If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and
661 line numbers for runtime errors are printed. If the first letter is
662 @samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers
663 for runtime errors. The default is to print the location.
665 @node GFORTRAN_OPTIONAL_PLUS
666 @section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted
668 If the first letter is @samp{y}, @samp{Y} or @samp{1},
669 a plus sign is printed
670 where permitted by the Fortran standard. If the first letter
671 is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed
672 in most cases. Default is not to print plus signs.
674 @node GFORTRAN_LIST_SEPARATOR
675 @section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output
677 This environment variable specifies the separator when writing
678 list-directed output. It may contain any number of spaces and
679 at most one comma. If you specify this on the command line,
680 be sure to quote spaces, as in
682 $ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out
684 when @command{a.out} is the compiled Fortran program that you want to run.
685 Default is a single space.
687 @node GFORTRAN_CONVERT_UNIT
688 @section @env{GFORTRAN_CONVERT_UNIT}---Set conversion for unformatted I/O
690 By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible
691 to change the representation of data for unformatted files.
692 The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable for
695 GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ;
696 mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ;
697 exception: mode ':' unit_list | unit_list ;
698 unit_list: unit_spec | unit_list unit_spec ;
699 unit_spec: INTEGER | INTEGER '-' INTEGER ;
701 The variable consists of an optional default mode, followed by
702 a list of optional exceptions, which are separated by semicolons
703 from the preceding default and each other. Each exception consists
704 of a format and a comma-separated list of units. Valid values for
705 the modes are the same as for the @code{CONVERT} specifier:
708 @item @code{NATIVE} Use the native format. This is the default.
709 @item @code{SWAP} Swap between little- and big-endian.
710 @item @code{LITTLE_ENDIAN} Use the little-endian format
711 for unformatted files.
712 @item @code{BIG_ENDIAN} Use the big-endian format for unformatted files.
714 For POWER systems which support @option{-mabi=ieeelongdouble},
715 there are additional options, which can be combined with the
716 others with commas. Those are
718 @item @code{R16_IEEE} Use IEEE 128-bit format for @code{REAL(KIND=16)}.
719 @item @code{R16_IBM} Use IBM @code{long double} format for
720 @code{REAL(KIND=16)}.
722 A missing mode for an exception is taken to mean @code{BIG_ENDIAN}.
723 Examples of values for @env{GFORTRAN_CONVERT_UNIT} are:
725 @item @code{'big_endian'} Do all unformatted I/O in big_endian mode.
726 @item @code{'little_endian;native:10-20,25'} Do all unformatted I/O
727 in little_endian mode, except for units 10 to 20 and 25, which are in
729 @item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native.
730 @item @code{'big_endian,r16_ibm'} Do all unformatted I/O in big-endian
731 mode and use IBM long double for output of @code{REAL(KIND=16)} values.
734 Setting the environment variables should be done on the command
735 line or via the @command{export}
736 command for @command{sh}-compatible shells and via @command{setenv}
737 for @command{csh}-compatible shells.
739 Example for @command{sh}:
742 $ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out
745 Example code for @command{csh}:
748 % setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20'
752 Using anything but the native representation for unformatted data
753 carries a significant speed overhead. If speed in this area matters
754 to you, it is best if you use this only for data that needs to be
757 @xref{CONVERT specifier}, for an alternative way to specify the
758 data representation for unformatted files. @xref{Runtime Options}, for
759 setting a default data representation for the whole program. The
760 @code{CONVERT} specifier overrides the @option{-fconvert} compile options.
762 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
763 environment variable will override the CONVERT specifier in the
764 open statement}. This is to give control over data formats to
765 users who do not have the source code of their program available.
767 @node GFORTRAN_ERROR_BACKTRACE
768 @section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors
770 If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to @samp{y},
771 @samp{Y} or @samp{1} (only the first letter is relevant) then a
772 backtrace is printed when a serious run-time error occurs. To disable
773 the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}.
774 Default is to print a backtrace unless the @option{-fno-backtrace}
775 compile option was used.
777 @node GFORTRAN_FORMATTED_BUFFER_SIZE
778 @section @env{GFORTRAN_FORMATTED_BUFFER_SIZE}---Set buffer size for formatted I/O
780 The @env{GFORTRAN_FORMATTED_BUFFER_SIZE} environment variable
781 specifies buffer size in bytes to be used for formatted output.
782 The default value is 8192.
784 @node GFORTRAN_UNFORMATTED_BUFFER_SIZE
785 @section @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE}---Set buffer size for unformatted I/O
787 The @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE} environment variable
788 specifies buffer size in bytes to be used for unformatted output.
789 The default value is 131072.
791 @c =====================================================================
792 @c PART II: LANGUAGE REFERENCE
793 @c =====================================================================
796 \part{II}{Language Reference}
801 @c ---------------------------------------------------------------------
802 @c Compiler Characteristics
803 @c ---------------------------------------------------------------------
805 @node Compiler Characteristics
806 @chapter Compiler Characteristics
808 This chapter describes certain characteristics of the GNU Fortran
809 compiler, that are not specified by the Fortran standard, but which
810 might in some way or another become visible to the programmer.
813 * KIND Type Parameters::
814 * Internal representation of LOGICAL variables::
815 * Evaluation of logical expressions::
816 * MAX and MIN intrinsics with REAL NaN arguments::
817 * Thread-safety of the runtime library::
818 * Data consistency and durability::
819 * Files opened without an explicit ACTION= specifier::
820 * File operations on symbolic links::
821 * File format of unformatted sequential files::
823 * Behavior on integer overflow::
827 @node KIND Type Parameters
828 @section KIND Type Parameters
831 The @code{KIND} type parameters supported by GNU Fortran for the primitive
837 1, 2, 4, 8*, 16*, default: 4**
840 1, 2, 4, 8*, 16*, default: 4**
843 4, 8, 10*, 16*, default: 4***
846 4, 8, 10*, 16*, default: 4***
848 @item DOUBLE PRECISION
849 4, 8, 10*, 16*, default: 8***
857 * not available on all systems @*
858 ** unless @option{-fdefault-integer-8} is used @*
859 *** unless @option{-fdefault-real-8} is used (see @ref{Fortran Dialect Options})
862 The @code{KIND} value matches the storage size in bytes, except for
863 @code{COMPLEX} where the storage size is twice as much (or both real and
864 imaginary part are a real value of the given size). It is recommended to use
865 the @ref{SELECTED_CHAR_KIND}, @ref{SELECTED_INT_KIND} and
866 @ref{SELECTED_REAL_KIND} intrinsics or the @code{INT8}, @code{INT16},
867 @code{INT32}, @code{INT64}, @code{REAL32}, @code{REAL64}, and @code{REAL128}
868 parameters of the @code{ISO_FORTRAN_ENV} module instead of the concrete values.
869 The available kind parameters can be found in the constant arrays
870 @code{CHARACTER_KINDS}, @code{INTEGER_KINDS}, @code{LOGICAL_KINDS} and
871 @code{REAL_KINDS} in the @ref{ISO_FORTRAN_ENV} module. For C interoperability,
872 the kind parameters of the @ref{ISO_C_BINDING} module should be used.
875 @node Internal representation of LOGICAL variables
876 @section Internal representation of LOGICAL variables
877 @cindex logical, variable representation
879 The Fortran standard does not specify how variables of @code{LOGICAL}
880 type are represented, beyond requiring that @code{LOGICAL} variables
881 of default kind have the same storage size as default @code{INTEGER}
882 and @code{REAL} variables. The GNU Fortran internal representation is
885 A @code{LOGICAL(KIND=N)} variable is represented as an
886 @code{INTEGER(KIND=N)} variable, however, with only two permissible
887 values: @code{1} for @code{.TRUE.} and @code{0} for
888 @code{.FALSE.}. Any other integer value results in undefined behavior.
890 See also @ref{Argument passing conventions} and @ref{Interoperability with C}.
893 @node Evaluation of logical expressions
894 @section Evaluation of logical expressions
896 The Fortran standard does not require the compiler to evaluate all parts of an
897 expression, if they do not contribute to the final result. For logical
898 expressions with @code{.AND.} or @code{.OR.} operators, in particular, GNU
899 Fortran will optimize out function calls (even to impure functions) if the
900 result of the expression can be established without them. However, since not
901 all compilers do that, and such an optimization can potentially modify the
902 program flow and subsequent results, GNU Fortran throws warnings for such
903 situations with the @option{-Wfunction-elimination} flag.
906 @node MAX and MIN intrinsics with REAL NaN arguments
907 @section MAX and MIN intrinsics with REAL NaN arguments
908 @cindex MAX, MIN, NaN
910 The Fortran standard does not specify what the result of the
911 @code{MAX} and @code{MIN} intrinsics are if one of the arguments is a
912 @code{NaN}. Accordingly, the GNU Fortran compiler does not specify
913 that either, as this allows for faster and more compact code to be
914 generated. If the programmer wishes to take some specific action in
915 case one of the arguments is a @code{NaN}, it is necessary to
916 explicitly test the arguments before calling @code{MAX} or @code{MIN},
917 e.g. with the @code{IEEE_IS_NAN} function from the intrinsic module
918 @code{IEEE_ARITHMETIC}.
921 @node Thread-safety of the runtime library
922 @section Thread-safety of the runtime library
923 @cindex thread-safety, threads
925 GNU Fortran can be used in programs with multiple threads, e.g.@: by
926 using OpenMP, by calling OS thread handling functions via the
927 @code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code
928 being called from a multi-threaded program.
930 The GNU Fortran runtime library, (@code{libgfortran}), supports being
931 called concurrently from multiple threads with the following
934 During library initialization, the C @code{getenv} function is used,
935 which need not be thread-safe. Similarly, the @code{getenv}
936 function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and
937 @code{GETENV} intrinsics. It is the responsibility of the user to
938 ensure that the environment is not being updated concurrently when any
939 of these actions are taking place.
941 The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are
942 implemented with the @code{system} function, which need not be
943 thread-safe. It is the responsibility of the user to ensure that
944 @code{system} is not called concurrently.
946 For platforms not supporting thread-safe POSIX functions, further
947 functionality might not be thread-safe. For details, please consult
948 the documentation for your operating system.
950 The GNU Fortran runtime library uses various C library functions that
951 depend on the locale, such as @code{strtod} and @code{snprintf}. In
952 order to work correctly in locale-aware programs that set the locale
953 using @code{setlocale}, the locale is reset to the default ``C''
954 locale while executing a formatted @code{READ} or @code{WRITE}
955 statement. On targets supporting the POSIX 2008 per-thread locale
956 functions (e.g. @code{newlocale}, @code{uselocale},
957 @code{freelocale}), these are used and thus the global locale set
958 using @code{setlocale} or the per-thread locales in other threads are
959 not affected. However, on targets lacking this functionality, the
960 global LC_NUMERIC locale is set to ``C'' during the formatted I/O.
961 Thus, on such targets it's not safe to call @code{setlocale}
962 concurrently from another thread while a Fortran formatted I/O
963 operation is in progress. Also, other threads doing something
964 dependent on the LC_NUMERIC locale might not work correctly if a
965 formatted I/O operation is in progress in another thread.
967 @node Data consistency and durability
968 @section Data consistency and durability
969 @cindex consistency, durability
971 This section contains a brief overview of data and metadata
972 consistency and durability issues when doing I/O.
974 With respect to durability, GNU Fortran makes no effort to ensure that
975 data is committed to stable storage. If this is required, the GNU
976 Fortran programmer can use the intrinsic @code{FNUM} to retrieve the
977 low level file descriptor corresponding to an open Fortran unit. Then,
978 using e.g. the @code{ISO_C_BINDING} feature, one can call the
979 underlying system call to flush dirty data to stable storage, such as
980 @code{fsync} on POSIX, @code{_commit} on MingW, or @code{fcntl(fd,
981 F_FULLSYNC, 0)} on macOS. The following example shows how to call
985 ! Declare the interface for POSIX fsync function
987 function fsync (fd) bind(c,name="fsync")
988 use iso_c_binding, only: c_int
989 integer(c_int), value :: fd
990 integer(c_int) :: fsync
994 ! Variable declaration
1001 ! Perform I/O on unit 10
1006 ret = fsync(fnum(10))
1008 ! Handle possible error
1009 if (ret /= 0) stop "Error calling FSYNC"
1012 With respect to consistency, for regular files GNU Fortran uses
1013 buffered I/O in order to improve performance. This buffer is flushed
1014 automatically when full and in some other situations, e.g. when
1015 closing a unit. It can also be explicitly flushed with the
1016 @code{FLUSH} statement. Also, the buffering can be turned off with the
1017 @code{GFORTRAN_UNBUFFERED_ALL} and
1018 @code{GFORTRAN_UNBUFFERED_PRECONNECTED} environment variables. Special
1019 files, such as terminals and pipes, are always unbuffered. Sometimes,
1020 however, further things may need to be done in order to allow other
1021 processes to see data that GNU Fortran has written, as follows.
1023 The Windows platform supports a relaxed metadata consistency model,
1024 where file metadata is written to the directory lazily. This means
1025 that, for instance, the @code{dir} command can show a stale size for a
1026 file. One can force a directory metadata update by closing the unit,
1027 or by calling @code{_commit} on the file descriptor. Note, though,
1028 that @code{_commit} will force all dirty data to stable storage, which
1029 is often a very slow operation.
1031 The Network File System (NFS) implements a relaxed consistency model
1032 called open-to-close consistency. Closing a file forces dirty data and
1033 metadata to be flushed to the server, and opening a file forces the
1034 client to contact the server in order to revalidate cached
1035 data. @code{fsync} will also force a flush of dirty data and metadata
1036 to the server. Similar to @code{open} and @code{close}, acquiring and
1037 releasing @code{fcntl} file locks, if the server supports them, will
1038 also force cache validation and flushing dirty data and metadata.
1041 @node Files opened without an explicit ACTION= specifier
1042 @section Files opened without an explicit ACTION= specifier
1043 @cindex open, action
1045 The Fortran standard says that if an @code{OPEN} statement is executed
1046 without an explicit @code{ACTION=} specifier, the default value is
1047 processor dependent. GNU Fortran behaves as follows:
1050 @item Attempt to open the file with @code{ACTION='READWRITE'}
1051 @item If that fails, try to open with @code{ACTION='READ'}
1052 @item If that fails, try to open with @code{ACTION='WRITE'}
1053 @item If that fails, generate an error
1057 @node File operations on symbolic links
1058 @section File operations on symbolic links
1059 @cindex file, symbolic link
1061 This section documents the behavior of GNU Fortran for file operations on
1062 symbolic links, on systems that support them.
1066 @item Results of INQUIRE statements of the ``inquire by file'' form will
1067 relate to the target of the symbolic link. For example,
1068 @code{INQUIRE(FILE="foo",EXIST=ex)} will set @var{ex} to @var{.true.} if
1069 @var{foo} is a symbolic link pointing to an existing file, and @var{.false.}
1070 if @var{foo} points to an non-existing file (``dangling'' symbolic link).
1072 @item Using the @code{OPEN} statement with a @code{STATUS="NEW"} specifier
1073 on a symbolic link will result in an error condition, whether the symbolic
1074 link points to an existing target or is dangling.
1076 @item If a symbolic link was connected, using the @code{CLOSE} statement
1077 with a @code{STATUS="DELETE"} specifier will cause the symbolic link itself
1078 to be deleted, not its target.
1082 @node File format of unformatted sequential files
1083 @section File format of unformatted sequential files
1084 @cindex file, unformatted sequential
1085 @cindex unformatted sequential
1086 @cindex sequential, unformatted
1087 @cindex record marker
1090 Unformatted sequential files are stored as logical records using
1091 record markers. Each logical record consists of one of more
1094 Each subrecord consists of a leading record marker, the data written
1095 by the user program, and a trailing record marker. The record markers
1096 are four-byte integers by default, and eight-byte integers if the
1097 @option{-fmax-subrecord-length=8} option (which exists for backwards
1098 compability only) is in effect.
1100 The representation of the record markers is that of unformatted files
1101 given with the @option{-fconvert} option, the @ref{CONVERT specifier}
1102 in an open statement or the @ref{GFORTRAN_CONVERT_UNIT} environment
1105 The maximum number of bytes of user data in a subrecord is 2147483639
1106 (2 GiB - 9) for a four-byte record marker. This limit can be lowered
1107 with the @option{-fmax-subrecord-length} option, although this is
1108 rarely useful. If the length of a logical record exceeds this limit,
1109 the data is distributed among several subrecords.
1111 The absolute of the number stored in the record markers is the number
1112 of bytes of user data in the corresponding subrecord. If the leading
1113 record marker of a subrecord contains a negative number, another
1114 subrecord follows the current one. If the trailing record marker
1115 contains a negative number, then there is a preceding subrecord.
1117 In the most simple case, with only one subrecord per logical record,
1118 both record markers contain the number of bytes of user data in the
1121 The format for unformatted sequential data can be duplicated using
1122 unformatted stream, as shown in the example program for an unformatted
1123 record containing a single subrecord:
1127 use iso_fortran_env, only: int32
1130 real, dimension(10) :: a, b
1131 call random_number(a)
1132 open (10,file='test.dat',form='unformatted',access='stream')
1133 inquire (iolength=i) a
1136 open (10,file='test.dat',form='unformatted')
1138 if (all (a == b)) print *,'success!'
1142 @node Asynchronous I/O
1143 @section Asynchronous I/O
1144 @cindex input/output, asynchronous
1145 @cindex asynchronous I/O
1147 Asynchronous I/O is supported if the program is linked against the
1148 POSIX thread library. If that is not the case, all I/O is performed
1149 as synchronous. On systems which do not support pthread condition
1150 variables, such as AIX, I/O is also performed as synchronous.
1152 On some systems, such as Darwin or Solaris, the POSIX thread library
1153 is always linked in, so asynchronous I/O is always performed. On other
1154 sytems, such as Linux, it is necessary to specify @option{-pthread},
1155 @option{-lpthread} or @option{-fopenmp} during the linking step.
1157 @c ---------------------------------------------------------------------
1159 @c ---------------------------------------------------------------------
1161 @c Maybe this chapter should be merged with the 'Standards' section,
1162 @c whenever that is written :-)
1164 @node Behavior on integer overflow
1165 @section Behavior on integer overflow
1166 @cindex integer overflow
1167 @cindex overflow handling
1169 Integer overflow is prohibited by the Fortran standard. The behavior
1170 of gfortran on integer overflow is undefined by default. Traditional
1171 code, like linear congruential pseudo-random number generators in old
1172 programs that rely on specific, non-standard behavior may generate
1173 unexpected results. The @option{-fsanitize=undefined} option can be
1174 used to detect such code at runtime.
1176 It is recommended to use the intrinsic subroutine @code{RANDOM_NUMBER}
1177 for random number generators or, if the old behavior is desired, to
1178 use the @option{-fwrapv} option. Note that this option can impact
1185 The two sections below detail the extensions to standard Fortran that are
1186 implemented in GNU Fortran, as well as some of the popular or
1187 historically important extensions that are not (or not yet) implemented.
1188 For the latter case, we explain the alternatives available to GNU Fortran
1189 users, including replacement by standard-conforming code or GNU
1193 * Extensions implemented in GNU Fortran::
1194 * Extensions not implemented in GNU Fortran::
1198 @node Extensions implemented in GNU Fortran
1199 @section Extensions implemented in GNU Fortran
1200 @cindex extensions, implemented
1202 GNU Fortran implements a number of extensions over standard Fortran.
1203 This chapter contains information on their syntax and meaning. There
1204 are currently two categories of GNU Fortran extensions, those that
1205 provide functionality beyond that provided by any standard, and those
1206 that are supported by GNU Fortran purely for backward compatibility
1207 with legacy compilers. By default, @option{-std=gnu} allows the
1208 compiler to accept both types of extensions, but to warn about the use
1209 of the latter. Specifying either @option{-std=f95},
1210 @option{-std=f2003}, @option{-std=f2008}, or @option{-std=f2018}
1211 disables both types of extensions, and @option{-std=legacy} allows
1212 both without warning. The special compile flag @option{-fdec} enables
1213 additional compatibility extensions along with those enabled by
1214 @option{-std=legacy}.
1217 * Old-style kind specifications::
1218 * Old-style variable initialization::
1219 * Extensions to namelist::
1220 * X format descriptor without count field::
1221 * Commas in FORMAT specifications::
1222 * Missing period in FORMAT specifications::
1223 * Default widths for F@comma{} G and I format descriptors::
1225 * @code{Q} exponent-letter::
1226 * BOZ literal constants::
1227 * Real array indices::
1229 * Implicitly convert LOGICAL and INTEGER values::
1230 * Hollerith constants support::
1231 * Character conversion::
1233 * CONVERT specifier::
1236 * Argument list functions::
1237 * Read/Write after EOF marker::
1238 * STRUCTURE and RECORD::
1240 * Type variants for integer intrinsics::
1241 * AUTOMATIC and STATIC attributes::
1242 * Form feed as whitespace::
1243 * TYPE as an alias for PRINT::
1244 * %LOC as an rvalue::
1246 * Bitwise logical operators::
1247 * Extended I/O specifiers::
1248 * Legacy PARAMETER statements::
1249 * Default exponents::
1252 @node Old-style kind specifications
1253 @subsection Old-style kind specifications
1254 @cindex kind, old-style
1256 GNU Fortran allows old-style kind specifications in declarations. These
1262 where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
1263 etc.), and where @code{size} is a byte count corresponding to the
1264 storage size of a valid kind for that type. (For @code{COMPLEX}
1265 variables, @code{size} is the total size of the real and imaginary
1266 parts.) The statement then declares @code{x}, @code{y} and @code{z} to
1267 be of type @code{TYPESPEC} with the appropriate kind. This is
1268 equivalent to the standard-conforming declaration
1273 where @code{k} is the kind parameter suitable for the intended precision. As
1274 kind parameters are implementation-dependent, use the @code{KIND},
1275 @code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve
1276 the correct value, for instance @code{REAL*8 x} can be replaced by:
1278 INTEGER, PARAMETER :: dbl = KIND(1.0d0)
1282 @node Old-style variable initialization
1283 @subsection Old-style variable initialization
1285 GNU Fortran allows old-style initialization of variables of the
1289 REAL x(2,2) /3*0.,1./
1291 The syntax for the initializers is as for the @code{DATA} statement, but
1292 unlike in a @code{DATA} statement, an initializer only applies to the
1293 variable immediately preceding the initialization. In other words,
1294 something like @code{INTEGER I,J/2,3/} is not valid. This style of
1295 initialization is only allowed in declarations without double colons
1296 (@code{::}); the double colons were introduced in Fortran 90, which also
1297 introduced a standard syntax for initializing variables in type
1300 Examples of standard-conforming code equivalent to the above example
1304 INTEGER :: i = 1, j = 2
1305 REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
1309 DATA i/1/, j/2/, x/3*0.,1./
1312 Note that variables which are explicitly initialized in declarations
1313 or in @code{DATA} statements automatically acquire the @code{SAVE}
1316 @node Extensions to namelist
1317 @subsection Extensions to namelist
1320 GNU Fortran fully supports the Fortran 95 standard for namelist I/O
1321 including array qualifiers, substrings and fully qualified derived types.
1322 The output from a namelist write is compatible with namelist read. The
1323 output has all names in upper case and indentation to column 1 after the
1324 namelist name. Two extensions are permitted:
1326 Old-style use of @samp{$} instead of @samp{&}
1329 X(:)%Y(2) = 1.0 2.0 3.0
1334 It should be noted that the default terminator is @samp{/} rather than
1337 Querying of the namelist when inputting from stdin. After at least
1338 one space, entering @samp{?} sends to stdout the namelist name and the names of
1339 the variables in the namelist:
1350 Entering @samp{=?} outputs the namelist to stdout, as if
1351 @code{WRITE(*,NML = mynml)} had been called:
1356 X(1)%Y= 0.000000 , 1.000000 , 0.000000 ,
1357 X(2)%Y= 0.000000 , 2.000000 , 0.000000 ,
1358 X(3)%Y= 0.000000 , 3.000000 , 0.000000 ,
1362 To aid this dialog, when input is from stdin, errors send their
1363 messages to stderr and execution continues, even if @code{IOSTAT} is set.
1365 @code{PRINT} namelist is permitted. This causes an error if
1366 @option{-std=f95} is used.
1369 REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/)
1372 END PROGRAM test_print
1375 Expanded namelist reads are permitted. This causes an error if
1376 @option{-std=f95} is used. In the following example, the first element
1377 of the array will be given the value 0.00 and the two succeeding
1378 elements will be given the values 1.00 and 2.00.
1381 X(1,1) = 0.00 , 1.00 , 2.00
1385 When writing a namelist, if no @code{DELIM=} is specified, by default a
1386 double quote is used to delimit character strings. If -std=F95, F2003,
1387 or F2008, etc, the delim status is set to 'none'. Defaulting to
1388 quotes ensures that namelists with character strings can be subsequently
1389 read back in accurately.
1391 @node X format descriptor without count field
1392 @subsection @code{X} format descriptor without count field
1394 To support legacy codes, GNU Fortran permits the count field of the
1395 @code{X} edit descriptor in @code{FORMAT} statements to be omitted.
1396 When omitted, the count is implicitly assumed to be one.
1400 10 FORMAT (I1, X, I1)
1403 @node Commas in FORMAT specifications
1404 @subsection Commas in @code{FORMAT} specifications
1406 To support legacy codes, GNU Fortran allows the comma separator
1407 to be omitted immediately before and after character string edit
1408 descriptors in @code{FORMAT} statements. A comma with no following format
1409 descriptor is permitted if the @option{-fdec-blank-format-item} is given on
1410 the command line. This is considered non-conforming code and is
1415 10 FORMAT ('FOO='I1' BAR='I2)
1421 @node Missing period in FORMAT specifications
1422 @subsection Missing period in @code{FORMAT} specifications
1424 To support legacy codes, GNU Fortran allows missing periods in format
1425 specifications if and only if @option{-std=legacy} is given on the
1426 command line. This is considered non-conforming code and is
1435 @node Default widths for F@comma{} G and I format descriptors
1436 @subsection Default widths for @code{F}, @code{G} and @code{I} format descriptors
1438 To support legacy codes, GNU Fortran allows width to be omitted from format
1439 specifications if and only if @option{-fdec-format-defaults} is given on the
1440 command line. Default widths will be used. This is considered non-conforming
1441 code and is discouraged.
1446 WRITE(*,10) value1, value1, value2
1447 10 FORMAT ('F, G, I')
1451 @node I/O item lists
1452 @subsection I/O item lists
1453 @cindex I/O item lists
1455 To support legacy codes, GNU Fortran allows the input item list
1456 of the @code{READ} statement, and the output item lists of the
1457 @code{WRITE} and @code{PRINT} statements, to start with a comma.
1459 @node @code{Q} exponent-letter
1460 @subsection @code{Q} exponent-letter
1461 @cindex @code{Q} exponent-letter
1463 GNU Fortran accepts real literal constants with an exponent-letter
1464 of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted
1465 as a @code{REAL(16)} entity on targets that support this type. If
1466 the target does not support @code{REAL(16)} but has a @code{REAL(10)}
1467 type, then the real-literal-constant will be interpreted as a
1468 @code{REAL(10)} entity. In the absence of @code{REAL(16)} and
1469 @code{REAL(10)}, an error will occur.
1471 @node BOZ literal constants
1472 @subsection BOZ literal constants
1473 @cindex BOZ literal constants
1475 Besides decimal constants, Fortran also supports binary (@code{b}),
1476 octal (@code{o}) and hexadecimal (@code{z}) integer constants. The
1477 syntax is: @samp{prefix quote digits quote}, where the prefix is
1478 either @code{b}, @code{o} or @code{z}, quote is either @code{'} or
1479 @code{"} and the digits are @code{0} or @code{1} for binary,
1480 between @code{0} and @code{7} for octal, and between @code{0} and
1481 @code{F} for hexadecimal. (Example: @code{b'01011101'}.)
1483 Up to Fortran 95, BOZ literal constants were only allowed to initialize
1484 integer variables in DATA statements. Since Fortran 2003 BOZ literal
1485 constants are also allowed as actual arguments to the @code{REAL},
1486 @code{DBLE}, @code{INT} and @code{CMPLX} intrinsic functions.
1487 The BOZ literal constant is simply a string of bits, which is padded
1488 or truncated as needed, during conversion to a numeric type. The
1489 Fortran standard states that the treatment of the sign bit is processor
1490 dependent. Gfortran interprets the sign bit as a user would expect.
1492 As a deprecated extension, GNU Fortran allows hexadecimal BOZ literal
1493 constants to be specified using the @code{X} prefix. That the BOZ literal
1494 constant can also be specified by adding a suffix to the string, for
1495 example, @code{Z'ABC'} and @code{'ABC'X} are equivalent. Additionally,
1496 as extension, BOZ literals are permitted in some contexts outside of
1497 @code{DATA} and the intrinsic functions listed in the Fortran standard.
1498 Use @option{-fallow-invalid-boz} to enable the extension.
1500 @node Real array indices
1501 @subsection Real array indices
1502 @cindex array, indices of type real
1504 As an extension, GNU Fortran allows the use of @code{REAL} expressions
1505 or variables as array indices.
1507 @node Unary operators
1508 @subsection Unary operators
1509 @cindex operators, unary
1511 As an extension, GNU Fortran allows unary plus and unary minus operators
1512 to appear as the second operand of binary arithmetic operators without
1513 the need for parenthesis.
1519 @node Implicitly convert LOGICAL and INTEGER values
1520 @subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values
1521 @cindex conversion, to integer
1522 @cindex conversion, to logical
1524 As an extension for backwards compatibility with other compilers, GNU
1525 Fortran allows the implicit conversion of @code{LOGICAL} values to
1526 @code{INTEGER} values and vice versa. When converting from a
1527 @code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as
1528 zero, and @code{.TRUE.} is interpreted as one. When converting from
1529 @code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as
1530 @code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}.
1541 However, there is no implicit conversion of @code{INTEGER} values in
1542 @code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values
1545 @node Hollerith constants support
1546 @subsection Hollerith constants support
1547 @cindex Hollerith constants
1549 GNU Fortran supports Hollerith constants in assignments, @code{DATA}
1550 statements, function and subroutine arguments. A Hollerith constant is
1551 written as a string of characters preceded by an integer constant
1552 indicating the character count, and the letter @code{H} or
1553 @code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER},
1554 @code{REAL}, or @code{COMPLEX}), @code{LOGICAL} or @code{CHARACTER} variable.
1555 The constant will be padded with spaces or truncated to fit the size of
1556 the variable in which it is stored.
1558 Examples of valid uses of Hollerith constants:
1561 data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/
1562 x(1) = 16HABCDEFGHIJKLMNOP
1566 Examples of Hollerith constants:
1569 a = 0H ! Invalid, at least one character is needed.
1571 a = 8H12345678 ! Valid, but the Hollerith constant will be truncated.
1572 a = 3Hxyz ! Valid, but the Hollerith constant will be padded.
1575 In general, Hollerith constants were used to provide a rudimentary
1576 facility for handling character strings in early Fortran compilers,
1577 prior to the introduction of @code{CHARACTER} variables in Fortran 77;
1578 in those cases, the standard-compliant equivalent is to convert the
1579 program to use proper character strings. On occasion, there may be a
1580 case where the intent is specifically to initialize a numeric variable
1581 with a given byte sequence. In these cases, the same result can be
1582 obtained by using the @code{TRANSFER} statement, as in this example.
1584 integer(kind=4) :: a
1585 a = transfer ("abcd", a) ! equivalent to: a = 4Habcd
1588 The use of the @option{-fdec} option extends support of Hollerith constants
1593 if (a .ne. 4habcd) then
1594 write(*,*) "no match"
1598 Supported types are numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}),
1599 and @code{CHARACTER}.
1601 @node Character conversion
1602 @subsection Character conversion
1603 @cindex conversion, to character
1605 Allowing character literals to be used in a similar way to Hollerith constants
1606 is a non-standard extension. This feature is enabled using
1607 -fdec-char-conversions and only applies to character literals of @code{kind=1}.
1609 Character literals can be used in @code{DATA} statements and assignments with
1610 numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}) or @code{LOGICAL}
1611 variables. Like Hollerith constants they are copied byte-wise fashion. The
1612 constant will be padded with spaces or truncated to fit the size of the
1613 variable in which it is stored.
1620 x = 'A' ! Will be padded.
1621 x = 'ab1234' ! Will be truncated.
1626 @subsection Cray pointers
1627 @cindex pointer, Cray
1629 Cray pointers are part of a non-standard extension that provides a
1630 C-like pointer in Fortran. This is accomplished through a pair of
1631 variables: an integer "pointer" that holds a memory address, and a
1632 "pointee" that is used to dereference the pointer.
1634 Pointer/pointee pairs are declared in statements of the form:
1636 pointer ( <pointer> , <pointee> )
1640 pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ...
1642 The pointer is an integer that is intended to hold a memory address.
1643 The pointee may be an array or scalar.
1644 If an assumed-size array is permitted within the scoping unit, a
1645 pointee can be an assumed-size array.
1646 That is, the last dimension may be left unspecified by using a @code{*}
1647 in place of a value. A pointee cannot be an assumed shape array.
1648 No space is allocated for the pointee.
1650 The pointee may have its type declared before or after the pointer
1651 statement, and its array specification (if any) may be declared
1652 before, during, or after the pointer statement. The pointer may be
1653 declared as an integer prior to the pointer statement. However, some
1654 machines have default integer sizes that are different than the size
1655 of a pointer, and so the following code is not portable:
1660 If a pointer is declared with a kind that is too small, the compiler
1661 will issue a warning; the resulting binary will probably not work
1662 correctly, because the memory addresses stored in the pointers may be
1663 truncated. It is safer to omit the first line of the above example;
1664 if explicit declaration of ipt's type is omitted, then the compiler
1665 will ensure that ipt is an integer variable large enough to hold a
1668 Pointer arithmetic is valid with Cray pointers, but it is not the same
1669 as C pointer arithmetic. Cray pointers are just ordinary integers, so
1670 the user is responsible for determining how many bytes to add to a
1671 pointer in order to increment it. Consider the following example:
1675 pointer (ipt, pointee)
1679 The last statement does not set @code{ipt} to the address of
1680 @code{target(1)}, as it would in C pointer arithmetic. Adding @code{1}
1681 to @code{ipt} just adds one byte to the address stored in @code{ipt}.
1683 Any expression involving the pointee will be translated to use the
1684 value stored in the pointer as the base address.
1686 To get the address of elements, this extension provides an intrinsic
1687 function @code{LOC()}. The @code{LOC()} function is equivalent to the
1688 @code{&} operator in C, except the address is cast to an integer type:
1691 pointer(ipt, arpte(10))
1693 ipt = loc(ar) ! Makes arpte is an alias for ar
1694 arpte(1) = 1.0 ! Sets ar(1) to 1.0
1696 The pointer can also be set by a call to the @code{MALLOC} intrinsic
1699 Cray pointees often are used to alias an existing variable. For
1707 As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for
1708 @code{target}. The optimizer, however, will not detect this aliasing, so
1709 it is unsafe to use @code{iarr} and @code{target} simultaneously. Using
1710 a pointee in any way that violates the Fortran aliasing rules or
1711 assumptions is illegal. It is the user's responsibility to avoid doing
1712 this; the compiler works under the assumption that no such aliasing
1715 Cray pointers will work correctly when there is no aliasing (i.e., when
1716 they are used to access a dynamically allocated block of memory), and
1717 also in any routine where a pointee is used, but any variable with which
1718 it shares storage is not used. Code that violates these rules may not
1719 run as the user intends. This is not a bug in the optimizer; any code
1720 that violates the aliasing rules is illegal. (Note that this is not
1721 unique to GNU Fortran; any Fortran compiler that supports Cray pointers
1722 will ``incorrectly'' optimize code with illegal aliasing.)
1724 There are a number of restrictions on the attributes that can be applied
1725 to Cray pointers and pointees. Pointees may not have the
1726 @code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY},
1727 @code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers
1728 may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET},
1729 @code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor
1730 may they be function results. Pointees may not occur in more than one
1731 pointer statement. A pointee cannot be a pointer. Pointees cannot occur
1732 in equivalence, common, or data statements.
1734 A Cray pointer may also point to a function or a subroutine. For
1735 example, the following excerpt is valid:
1739 pointer (subptr,subpte)
1749 A pointer may be modified during the course of a program, and this
1750 will change the location to which the pointee refers. However, when
1751 pointees are passed as arguments, they are treated as ordinary
1752 variables in the invoked function. Subsequent changes to the pointer
1753 will not change the base address of the array that was passed.
1755 @node CONVERT specifier
1756 @subsection @code{CONVERT} specifier
1757 @cindex @code{CONVERT} specifier
1759 GNU Fortran allows the conversion of unformatted data between little-
1760 and big-endian representation to facilitate moving of data
1761 between different systems. The conversion can be indicated with
1762 the @code{CONVERT} specifier on the @code{OPEN} statement.
1763 @xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying
1764 the data format via an environment variable.
1766 Valid values for @code{CONVERT} on most systems are:
1768 @item @code{CONVERT='NATIVE'} Use the native format. This is the default.
1769 @item @code{CONVERT='SWAP'} Swap between little- and big-endian.
1770 @item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation
1771 for unformatted files.
1772 @item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for
1775 On POWER systems which support @option{-mabi=ieeelongdouble},
1776 there are additional options, which can be combined with the others
1777 with commas. Those are
1779 @item @code{CONVERT='R16_IEEE'} Use IEEE 128-bit format for
1780 @code{REAL(KIND=16)}.
1781 @item @code{CONVERT='R16_IBM'} Use IBM @code{long double} format for
1782 real@code{REAL(KIND=16)}.
1785 Using the option could look like this:
1787 open(file='big.dat',form='unformatted',access='sequential', &
1788 convert='big_endian')
1791 The value of the conversion can be queried by using
1792 @code{INQUIRE(CONVERT=ch)}. The values returned are
1793 @code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}.
1795 @code{CONVERT} works between big- and little-endian for
1796 @code{INTEGER} values of all supported kinds and for @code{REAL}
1797 on IEEE systems of kinds 4 and 8. Conversion between different
1798 ``extended double'' types on different architectures such as
1799 m68k and x86_64, which GNU Fortran
1800 supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will
1803 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
1804 environment variable will override the CONVERT specifier in the
1805 open statement}. This is to give control over data formats to
1806 users who do not have the source code of their program available.
1808 Using anything but the native representation for unformatted data
1809 carries a significant speed overhead. If speed in this area matters
1810 to you, it is best if you use this only for data that needs to be
1817 OpenMP (Open Multi-Processing) is an application programming
1818 interface (API) that supports multi-platform shared memory
1819 multiprocessing programming in C/C++ and Fortran on many
1820 architectures, including Unix and Microsoft Windows platforms.
1821 It consists of a set of compiler directives, library routines,
1822 and environment variables that influence run-time behavior.
1824 GNU Fortran strives to be compatible to the
1825 @uref{https://openmp.org/specifications/,
1826 OpenMP Application Program Interface v4.5}.
1828 To enable the processing of the OpenMP directive @code{!$omp} in
1829 free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp}
1830 directives in fixed form; the @code{!$} conditional compilation sentinels
1831 in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels
1832 in fixed form, @command{gfortran} needs to be invoked with the
1833 @option{-fopenmp}. This also arranges for automatic linking of the
1834 GNU Offloading and Multi Processing Runtime Library
1835 @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
1838 The OpenMP Fortran runtime library routines are provided both in a
1839 form of a Fortran 90 module named @code{omp_lib} and in a form of
1840 a Fortran @code{include} file named @file{omp_lib.h}.
1842 An example of a parallelized loop taken from Appendix A.1 of
1843 the OpenMP Application Program Interface v2.5:
1845 SUBROUTINE A1(N, A, B)
1848 !$OMP PARALLEL DO !I is private by default
1850 B(I) = (A(I) + A(I-1)) / 2.0
1852 !$OMP END PARALLEL DO
1859 @option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays
1860 will be allocated on the stack. When porting existing code to OpenMP,
1861 this may lead to surprising results, especially to segmentation faults
1862 if the stacksize is limited.
1865 On glibc-based systems, OpenMP enabled applications cannot be statically
1866 linked due to limitations of the underlying pthreads-implementation. It
1867 might be possible to get a working solution if
1868 @command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added
1869 to the command line. However, this is not supported by @command{gcc} and
1870 thus not recommended.
1877 OpenACC is an application programming interface (API) that supports
1878 offloading of code to accelerator devices. It consists of a set of
1879 compiler directives, library routines, and environment variables that
1880 influence run-time behavior.
1882 GNU Fortran strives to be compatible to the
1883 @uref{https://www.openacc.org/, OpenACC Application Programming
1886 To enable the processing of the OpenACC directive @code{!$acc} in
1887 free-form source code; the @code{c$acc}, @code{*$acc} and @code{!$acc}
1888 directives in fixed form; the @code{!$} conditional compilation
1889 sentinels in free form; and the @code{c$}, @code{*$} and @code{!$}
1890 sentinels in fixed form, @command{gfortran} needs to be invoked with
1891 the @option{-fopenacc}. This also arranges for automatic linking of
1892 the GNU Offloading and Multi Processing Runtime Library
1893 @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
1896 The OpenACC Fortran runtime library routines are provided both in a
1897 form of a Fortran 90 module named @code{openacc} and in a form of a
1898 Fortran @code{include} file named @file{openacc_lib.h}.
1900 @node Argument list functions
1901 @subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC}
1902 @cindex argument list functions
1907 GNU Fortran supports argument list functions @code{%VAL}, @code{%REF}
1908 and @code{%LOC} statements, for backward compatibility with g77.
1909 It is recommended that these should be used only for code that is
1910 accessing facilities outside of GNU Fortran, such as operating system
1911 or windowing facilities. It is best to constrain such uses to isolated
1912 portions of a program--portions that deal specifically and exclusively
1913 with low-level, system-dependent facilities. Such portions might well
1914 provide a portable interface for use by the program as a whole, but are
1915 themselves not portable, and should be thoroughly tested each time they
1916 are rebuilt using a new compiler or version of a compiler.
1918 @code{%VAL} passes a scalar argument by value, @code{%REF} passes it by
1919 reference and @code{%LOC} passes its memory location. Since gfortran
1920 already passes scalar arguments by reference, @code{%REF} is in effect
1921 a do-nothing. @code{%LOC} has the same effect as a Fortran pointer.
1923 An example of passing an argument by value to a C subroutine foo.:
1926 C prototype void foo_ (float x);
1935 For details refer to the g77 manual
1936 @uref{https://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}.
1938 Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the
1939 GNU Fortran testsuite are worth a look.
1941 @node Read/Write after EOF marker
1942 @subsection Read/Write after EOF marker
1944 @cindex @code{BACKSPACE}
1945 @cindex @code{REWIND}
1947 Some legacy codes rely on allowing @code{READ} or @code{WRITE} after the
1948 EOF file marker in order to find the end of a file. GNU Fortran normally
1949 rejects these codes with a run-time error message and suggests the user
1950 consider @code{BACKSPACE} or @code{REWIND} to properly position
1951 the file before the EOF marker. As an extension, the run-time error may
1952 be disabled using -std=legacy.
1955 @node STRUCTURE and RECORD
1956 @subsection @code{STRUCTURE} and @code{RECORD}
1957 @cindex @code{STRUCTURE}
1958 @cindex @code{RECORD}
1960 Record structures are a pre-Fortran-90 vendor extension to create
1961 user-defined aggregate data types. Support for record structures in GNU
1962 Fortran can be enabled with the @option{-fdec-structure} compile flag.
1963 If you have a choice, you should instead use Fortran 90's ``derived types'',
1964 which have a different syntax.
1966 In many cases, record structures can easily be converted to derived types.
1967 To convert, replace @code{STRUCTURE /}@var{structure-name}@code{/}
1968 by @code{TYPE} @var{type-name}. Additionally, replace
1969 @code{RECORD /}@var{structure-name}@code{/} by
1970 @code{TYPE(}@var{type-name}@code{)}. Finally, in the component access,
1971 replace the period (@code{.}) by the percent sign (@code{%}).
1973 Here is an example of code using the non portable record structure syntax:
1976 ! Declaring a structure named ``item'' and containing three fields:
1977 ! an integer ID, an description string and a floating-point price.
1980 CHARACTER(LEN=200) description
1984 ! Define two variables, an single record of type ``item''
1985 ! named ``pear'', and an array of items named ``store_catalog''
1986 RECORD /item/ pear, store_catalog(100)
1988 ! We can directly access the fields of both variables
1990 pear.description = "juicy D'Anjou pear"
1992 store_catalog(7).id = 7831
1993 store_catalog(7).description = "milk bottle"
1994 store_catalog(7).price = 1.2
1996 ! We can also manipulate the whole structure
1997 store_catalog(12) = pear
1998 print *, store_catalog(12)
2002 This code can easily be rewritten in the Fortran 90 syntax as following:
2005 ! ``STRUCTURE /name/ ... END STRUCTURE'' becomes
2006 ! ``TYPE name ... END TYPE''
2009 CHARACTER(LEN=200) description
2013 ! ``RECORD /name/ variable'' becomes ``TYPE(name) variable''
2014 TYPE(item) pear, store_catalog(100)
2016 ! Instead of using a dot (.) to access fields of a record, the
2017 ! standard syntax uses a percent sign (%)
2019 pear%description = "juicy D'Anjou pear"
2021 store_catalog(7)%id = 7831
2022 store_catalog(7)%description = "milk bottle"
2023 store_catalog(7)%price = 1.2
2025 ! Assignments of a whole variable do not change
2026 store_catalog(12) = pear
2027 print *, store_catalog(12)
2031 GNU Fortran implements STRUCTURES like derived types with the following
2032 rules and exceptions:
2035 @item Structures act like derived types with the @code{SEQUENCE} attribute.
2036 Otherwise they may contain no specifiers.
2038 @item Structures may contain a special field with the name @code{%FILL}.
2039 This will create an anonymous component which cannot be accessed but occupies
2040 space just as if a component of the same type was declared in its place, useful
2041 for alignment purposes. As an example, the following structure will consist
2042 of at least sixteen bytes:
2052 @item Structures may share names with other symbols. For example, the following
2053 is invalid for derived types, but valid for structures:
2059 record /header/ header
2062 @item Structure types may be declared nested within another parent structure.
2065 structure /type-name/
2067 structure [/<type-name>/] <field-list>
2071 The type name may be ommitted, in which case the structure type itself is
2072 anonymous, and other structures of the same type cannot be instantiated. The
2073 following shows some examples:
2076 structure /appointment/
2077 ! nested structure definition: app_time is an array of two 'time'
2078 structure /time/ app_time (2)
2079 integer(1) hour, minute
2084 ! The 'time' structure is still usable
2090 structure /appointment/
2091 ! anonymous nested structure definition
2092 structure start, end
2093 integer(1) hour, minute
2099 @item Structures may contain @code{UNION} blocks. For more detail see the
2100 section on @ref{UNION and MAP}.
2102 @item Structures support old-style initialization of components, like
2103 those described in @ref{Old-style variable initialization}. For array
2104 initializers, an initializer may contain a repeat specification of the form
2105 @code{<literal-integer> * <constant-initializer>}. The value of the integer
2106 indicates the number of times to repeat the constant initializer when expanding
2107 the initializer list.
2111 @subsection @code{UNION} and @code{MAP}
2112 @cindex @code{UNION}
2115 Unions are an old vendor extension which were commonly used with the
2116 non-standard @ref{STRUCTURE and RECORD} extensions. Use of @code{UNION} and
2117 @code{MAP} is automatically enabled with @option{-fdec-structure}.
2119 A @code{UNION} declaration occurs within a structure; within the definition of
2120 each union is a number of @code{MAP} blocks. Each @code{MAP} shares storage
2121 with its sibling maps (in the same union), and the size of the union is the
2122 size of the largest map within it, just as with unions in C. The major
2123 difference is that component references do not indicate which union or map the
2124 component is in (the compiler gets to figure that out).
2126 Here is a small example:
2131 character(2) w0, w1, w2
2139 record /myunion/ rec
2140 ! After this assignment...
2143 ! The following is true:
2149 The two maps share memory, and the size of the union is ultimately six bytes:
2152 0 1 2 3 4 5 6 Byte offset
2153 -------------------------------
2155 -------------------------------
2158 \-------/ \-------/ \-------/
2161 \---------------------------/
2164 Following is an example mirroring the layout of an Intel x86_64 register:
2173 character(8) rh ! rah
2176 character(8) rl ! ral
2179 character(8) ex ! eax
2182 character(4) eh ! eah
2185 character(4) el ! eal
2202 ! After this assignment...
2203 a.rx = 'AAAAAAAA.BBB.C.D'
2205 ! The following is true:
2206 a.rx === 'AAAAAAAA.BBB.C.D'
2217 @node Type variants for integer intrinsics
2218 @subsection Type variants for integer intrinsics
2219 @cindex intrinsics, integer
2221 Similar to the D/C prefixes to real functions to specify the input/output
2222 types, GNU Fortran offers B/I/J/K prefixes to integer functions for
2223 compatibility with DEC programs. The types implied by each are:
2226 @code{B} - @code{INTEGER(kind=1)}
2227 @code{I} - @code{INTEGER(kind=2)}
2228 @code{J} - @code{INTEGER(kind=4)}
2229 @code{K} - @code{INTEGER(kind=8)}
2232 GNU Fortran supports these with the flag @option{-fdec-intrinsic-ints}.
2233 Intrinsics for which prefixed versions are available and in what form are noted
2234 in @ref{Intrinsic Procedures}. The complete list of supported intrinsics is
2237 @multitable @columnfractions .2 .2 .2 .2 .2
2239 @headitem Intrinsic @tab B @tab I @tab J @tab K
2241 @item @code{@ref{ABS}}
2242 @tab @code{BABS} @tab @code{IIABS} @tab @code{JIABS} @tab @code{KIABS}
2243 @item @code{@ref{BTEST}}
2244 @tab @code{BBTEST} @tab @code{BITEST} @tab @code{BJTEST} @tab @code{BKTEST}
2245 @item @code{@ref{IAND}}
2246 @tab @code{BIAND} @tab @code{IIAND} @tab @code{JIAND} @tab @code{KIAND}
2247 @item @code{@ref{IBCLR}}
2248 @tab @code{BBCLR} @tab @code{IIBCLR} @tab @code{JIBCLR} @tab @code{KIBCLR}
2249 @item @code{@ref{IBITS}}
2250 @tab @code{BBITS} @tab @code{IIBITS} @tab @code{JIBITS} @tab @code{KIBITS}
2251 @item @code{@ref{IBSET}}
2252 @tab @code{BBSET} @tab @code{IIBSET} @tab @code{JIBSET} @tab @code{KIBSET}
2253 @item @code{@ref{IEOR}}
2254 @tab @code{BIEOR} @tab @code{IIEOR} @tab @code{JIEOR} @tab @code{KIEOR}
2255 @item @code{@ref{IOR}}
2256 @tab @code{BIOR} @tab @code{IIOR} @tab @code{JIOR} @tab @code{KIOR}
2257 @item @code{@ref{ISHFT}}
2258 @tab @code{BSHFT} @tab @code{IISHFT} @tab @code{JISHFT} @tab @code{KISHFT}
2259 @item @code{@ref{ISHFTC}}
2260 @tab @code{BSHFTC} @tab @code{IISHFTC} @tab @code{JISHFTC} @tab @code{KISHFTC}
2261 @item @code{@ref{MOD}}
2262 @tab @code{BMOD} @tab @code{IMOD} @tab @code{JMOD} @tab @code{KMOD}
2263 @item @code{@ref{NOT}}
2264 @tab @code{BNOT} @tab @code{INOT} @tab @code{JNOT} @tab @code{KNOT}
2265 @item @code{@ref{REAL}}
2266 @tab @code{--} @tab @code{FLOATI} @tab @code{FLOATJ} @tab @code{FLOATK}
2269 @node AUTOMATIC and STATIC attributes
2270 @subsection @code{AUTOMATIC} and @code{STATIC} attributes
2271 @cindex variable attributes
2272 @cindex @code{AUTOMATIC}
2273 @cindex @code{STATIC}
2275 With @option{-fdec-static} GNU Fortran supports the DEC extended attributes
2276 @code{STATIC} and @code{AUTOMATIC} to provide explicit specification of entity
2277 storage. These follow the syntax of the Fortran standard @code{SAVE} attribute.
2279 @code{STATIC} is exactly equivalent to @code{SAVE}, and specifies that
2280 an entity should be allocated in static memory. As an example, @code{STATIC}
2281 local variables will retain their values across multiple calls to a function.
2283 Entities marked @code{AUTOMATIC} will be stack automatic whenever possible.
2284 @code{AUTOMATIC} is the default for local variables smaller than
2285 @option{-fmax-stack-var-size}, unless @option{-fno-automatic} is given. This
2286 attribute overrides @option{-fno-automatic}, @option{-fmax-stack-var-size}, and
2287 blanket @code{SAVE} statements.
2294 integer, automatic :: i ! automatic variable
2295 integer x, y ! static variables
2302 integer a, b, c, x, y, z
2306 ! a, b, c, and z are automatic
2307 ! x and y are static
2311 ! Compiled with -fno-automatic
2315 ! a is automatic; b, c, and d are static
2319 @node Form feed as whitespace
2320 @subsection Form feed as whitespace
2321 @cindex form feed whitespace
2323 Historically, legacy compilers allowed insertion of form feed characters ('\f',
2324 ASCII 0xC) at the beginning of lines for formatted output to line printers,
2325 though the Fortran standard does not mention this. GNU Fortran supports the
2326 interpretation of form feed characters in source as whitespace for
2329 @node TYPE as an alias for PRINT
2330 @subsection TYPE as an alias for PRINT
2331 @cindex type alias print
2332 For compatibility, GNU Fortran will interpret @code{TYPE} statements as
2333 @code{PRINT} statements with the flag @option{-fdec}. With this flag asserted,
2334 the following two examples are equivalent:
2337 TYPE *, 'hello world'
2341 PRINT *, 'hello world'
2344 @node %LOC as an rvalue
2345 @subsection %LOC as an rvalue
2347 Normally @code{%LOC} is allowed only in parameter lists. However the intrinsic
2348 function @code{LOC} does the same thing, and is usable as the right-hand-side of
2349 assignments. For compatibility, GNU Fortran supports the use of @code{%LOC} as
2350 an alias for the builtin @code{LOC} with @option{-std=legacy}. With this
2351 feature enabled the following two examples are equivalent:
2364 @node .XOR. operator
2365 @subsection .XOR. operator
2366 @cindex operators, xor
2368 GNU Fortran supports @code{.XOR.} as a logical operator with @code{-std=legacy}
2369 for compatibility with legacy code. @code{.XOR.} is equivalent to
2370 @code{.NEQV.}. That is, the output is true if and only if the inputs differ.
2372 @node Bitwise logical operators
2373 @subsection Bitwise logical operators
2374 @cindex logical, bitwise
2376 With @option{-fdec}, GNU Fortran relaxes the type constraints on
2377 logical operators to allow integer operands, and performs the corresponding
2378 bitwise operation instead. This flag is for compatibility only, and should be
2379 avoided in new code. Consider:
2388 In this example, compiled with @option{-fdec}, GNU Fortran will
2389 replace the @code{.AND.} operation with a call to the intrinsic
2390 @code{@ref{IAND}} function, yielding the bitwise-and of @code{i} and @code{j}.
2392 Note that this conversion will occur if at least one operand is of integral
2393 type. As a result, a logical operand will be converted to an integer when the
2394 other operand is an integer in a logical operation. In this case,
2395 @code{.TRUE.} is converted to @code{1} and @code{.FALSE.} to @code{0}.
2397 Here is the mapping of logical operator to bitwise intrinsic used with
2400 @multitable @columnfractions .25 .25 .5
2401 @headitem Operator @tab Intrinsic @tab Bitwise operation
2402 @item @code{.NOT.} @tab @code{@ref{NOT}} @tab complement
2403 @item @code{.AND.} @tab @code{@ref{IAND}} @tab intersection
2404 @item @code{.OR.} @tab @code{@ref{IOR}} @tab union
2405 @item @code{.NEQV.} @tab @code{@ref{IEOR}} @tab exclusive or
2406 @item @code{.EQV.} @tab @code{@ref{NOT}(@ref{IEOR})} @tab complement of exclusive or
2409 @node Extended I/O specifiers
2410 @subsection Extended I/O specifiers
2411 @cindex @code{CARRIAGECONTROL}
2412 @cindex @code{READONLY}
2413 @cindex @code{SHARE}
2414 @cindex @code{SHARED}
2415 @cindex @code{NOSHARED}
2416 @cindex I/O specifiers
2418 GNU Fortran supports the additional legacy I/O specifiers
2419 @code{CARRIAGECONTROL}, @code{READONLY}, and @code{SHARE} with the
2420 compile flag @option{-fdec}, for compatibility.
2423 @item CARRIAGECONTROL
2424 The @code{CARRIAGECONTROL} specifier allows a user to control line
2425 termination settings between output records for an I/O unit. The specifier has
2426 no meaning for readonly files. When @code{CARRAIGECONTROL} is specified upon
2427 opening a unit for formatted writing, the exact @code{CARRIAGECONTROL} setting
2428 determines what characters to write between output records. The syntax is:
2431 OPEN(..., CARRIAGECONTROL=cc)
2434 Where @emph{cc} is a character expression that evaluates to one of the
2437 @multitable @columnfractions .2 .8
2438 @item @code{'LIST'} @tab One line feed between records (default)
2439 @item @code{'FORTRAN'} @tab Legacy interpretation of the first character (see below)
2440 @item @code{'NONE'} @tab No separator between records
2443 With @code{CARRIAGECONTROL='FORTRAN'}, when a record is written, the first
2444 character of the input record is not written, and instead determines the output
2445 record separator as follows:
2447 @multitable @columnfractions .3 .3 .4
2448 @headitem Leading character @tab Meaning @tab Output separating character(s)
2449 @item @code{'+'} @tab Overprinting @tab Carriage return only
2450 @item @code{'-'} @tab New line @tab Line feed and carriage return
2451 @item @code{'0'} @tab Skip line @tab Two line feeds and carriage return
2452 @item @code{'1'} @tab New page @tab Form feed and carriage return
2453 @item @code{'$'} @tab Prompting @tab Line feed (no carriage return)
2454 @item @code{CHAR(0)} @tab Overprinting (no advance) @tab None
2458 The @code{READONLY} specifier may be given upon opening a unit, and is
2459 equivalent to specifying @code{ACTION='READ'}, except that the file may not be
2460 deleted on close (i.e. @code{CLOSE} with @code{STATUS="DELETE"}). The syntax
2464 @code{OPEN(..., READONLY)}
2468 The @code{SHARE} specifier allows system-level locking on a unit upon opening
2469 it for controlled access from multiple processes/threads. The @code{SHARE}
2470 specifier has several forms:
2478 Where @emph{sh} in the first form is a character expression that evaluates to
2479 a value as seen in the table below. The latter two forms are aliases
2480 for particular values of @emph{sh}:
2482 @multitable @columnfractions .3 .3 .4
2483 @headitem Explicit form @tab Short form @tab Meaning
2484 @item @code{SHARE='DENYRW'} @tab @code{NOSHARED} @tab Exclusive (write) lock
2485 @item @code{SHARE='DENYNONE'} @tab @code{SHARED} @tab Shared (read) lock
2488 In general only one process may hold an exclusive (write) lock for a given file
2489 at a time, whereas many processes may hold shared (read) locks for the same
2492 The behavior of locking may vary with your operating system. On POSIX systems,
2493 locking is implemented with @code{fcntl}. Consult your corresponding operating
2494 system's manual pages for further details. Locking via @code{SHARE=} is not
2495 supported on other systems.
2499 @node Legacy PARAMETER statements
2500 @subsection Legacy PARAMETER statements
2503 For compatibility, GNU Fortran supports legacy PARAMETER statements without
2504 parentheses with @option{-std=legacy}. A warning is emitted if used with
2505 @option{-std=gnu}, and an error is acknowledged with a real Fortran standard
2506 flag (@option{-std=f95}, etc...). These statements take the following form:
2510 parameter e = 2.718282
2515 @node Default exponents
2516 @subsection Default exponents
2519 For compatibility, GNU Fortran supports a default exponent of zero in real
2520 constants with @option{-fdec}. For example, @code{9e} would be
2521 interpreted as @code{9e0}, rather than an error.
2524 @node Extensions not implemented in GNU Fortran
2525 @section Extensions not implemented in GNU Fortran
2526 @cindex extensions, not implemented
2528 The long history of the Fortran language, its wide use and broad
2529 userbase, the large number of different compiler vendors and the lack of
2530 some features crucial to users in the first standards have lead to the
2531 existence of a number of important extensions to the language. While
2532 some of the most useful or popular extensions are supported by the GNU
2533 Fortran compiler, not all existing extensions are supported. This section
2534 aims at listing these extensions and offering advice on how best make
2535 code that uses them running with the GNU Fortran compiler.
2537 @c More can be found here:
2538 @c -- https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html
2539 @c -- the list of Fortran and libgfortran bugs closed as WONTFIX:
2540 @c http://tinyurl.com/2u4h5y
2543 * ENCODE and DECODE statements::
2544 * Variable FORMAT expressions::
2545 @c * TYPE and ACCEPT I/O Statements::
2546 @c * DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers::
2547 @c * Omitted arguments in procedure call::
2548 * Alternate complex function syntax::
2549 * Volatile COMMON blocks::
2550 * OPEN( ... NAME=)::
2551 * Q edit descriptor::
2554 @node ENCODE and DECODE statements
2555 @subsection @code{ENCODE} and @code{DECODE} statements
2556 @cindex @code{ENCODE}
2557 @cindex @code{DECODE}
2559 GNU Fortran does not support the @code{ENCODE} and @code{DECODE}
2560 statements. These statements are best replaced by @code{READ} and
2561 @code{WRITE} statements involving internal files (@code{CHARACTER}
2562 variables and arrays), which have been part of the Fortran standard since
2563 Fortran 77. For example, replace a code fragment like
2568 c ... Code that sets LINE
2569 DECODE (80, 9000, LINE) A, B, C
2570 9000 FORMAT (1X, 3(F10.5))
2577 CHARACTER(LEN=80) LINE
2579 c ... Code that sets LINE
2580 READ (UNIT=LINE, FMT=9000) A, B, C
2581 9000 FORMAT (1X, 3(F10.5))
2584 Similarly, replace a code fragment like
2589 c ... Code that sets A, B and C
2590 ENCODE (80, 9000, LINE) A, B, C
2591 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2598 CHARACTER(LEN=80) LINE
2600 c ... Code that sets A, B and C
2601 WRITE (UNIT=LINE, FMT=9000) A, B, C
2602 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2606 @node Variable FORMAT expressions
2607 @subsection Variable @code{FORMAT} expressions
2608 @cindex @code{FORMAT}
2610 A variable @code{FORMAT} expression is format statement which includes
2611 angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU
2612 Fortran does not support this legacy extension. The effect of variable
2613 format expressions can be reproduced by using the more powerful (and
2614 standard) combination of internal output and string formats. For example,
2615 replace a code fragment like this:
2626 c Variable declaration
2627 CHARACTER(LEN=20) FMT
2629 c Other code here...
2631 WRITE(FMT,'("(I", I0, ")")') N+1
2639 c Variable declaration
2640 CHARACTER(LEN=20) FMT
2642 c Other code here...
2645 WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1
2649 @node Alternate complex function syntax
2650 @subsection Alternate complex function syntax
2651 @cindex Complex function
2653 Some Fortran compilers, including @command{g77}, let the user declare
2654 complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as
2655 well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy
2656 extensions. @command{gfortran} accepts the latter form, which is more
2657 common, but not the former.
2660 @node Volatile COMMON blocks
2661 @subsection Volatile @code{COMMON} blocks
2662 @cindex @code{VOLATILE}
2663 @cindex @code{COMMON}
2665 Some Fortran compilers, including @command{g77}, let the user declare
2666 @code{COMMON} with the @code{VOLATILE} attribute. This is
2667 invalid standard Fortran syntax and is not supported by
2668 @command{gfortran}. Note that @command{gfortran} accepts
2669 @code{VOLATILE} variables in @code{COMMON} blocks since revision 4.3.
2672 @node OPEN( ... NAME=)
2673 @subsection @code{OPEN( ... NAME=)}
2676 Some Fortran compilers, including @command{g77}, let the user declare
2677 @code{OPEN( ... NAME=)}. This is
2678 invalid standard Fortran syntax and is not supported by
2679 @command{gfortran}. @code{OPEN( ... NAME=)} should be replaced
2680 with @code{OPEN( ... FILE=)}.
2682 @node Q edit descriptor
2683 @subsection @code{Q} edit descriptor
2684 @cindex @code{Q} edit descriptor
2686 Some Fortran compilers provide the @code{Q} edit descriptor, which
2687 transfers the number of characters left within an input record into an
2690 A direct replacement of the @code{Q} edit descriptor is not available
2691 in @command{gfortran}. How to replicate its functionality using
2692 standard-conforming code depends on what the intent of the original
2695 Options to replace @code{Q} may be to read the whole line into a
2696 character variable and then counting the number of non-blank
2697 characters left using @code{LEN_TRIM}. Another method may be to use
2698 formatted stream, read the data up to the position where the @code{Q}
2699 descriptor occurred, use @code{INQUIRE} to get the file position,
2700 count the characters up to the next @code{NEW_LINE} and then start
2701 reading from the position marked previously.
2704 @c ---------------------------------------------------------------------
2705 @c ---------------------------------------------------------------------
2706 @c Mixed-Language Programming
2707 @c ---------------------------------------------------------------------
2709 @node Mixed-Language Programming
2710 @chapter Mixed-Language Programming
2711 @cindex Interoperability
2712 @cindex Mixed-language programming
2715 * Interoperability with C::
2716 * GNU Fortran Compiler Directives::
2717 * Non-Fortran Main Program::
2718 * Naming and argument-passing conventions::
2721 This chapter is about mixed-language interoperability, but also
2722 applies if you link Fortran code compiled by different compilers. In
2723 most cases, use of the C Binding features of the Fortran 2003 and
2724 later standards is sufficient.
2726 For example, it is possible to mix Fortran code with C++ code as well
2727 as C, if you declare the interface functions as @code{extern "C"} on
2728 the C++ side and @code{BIND(C)} on the Fortran side, and follow the
2729 rules for interoperability with C. Note that you cannot manipulate
2730 C++ class objects in Fortran or vice versa except as opaque pointers.
2732 You can use the @command{gfortran} command to link both Fortran and
2733 non-Fortran code into the same program, or you can use @command{gcc}
2734 or @command{g++} if you also add an explicit @option{-lgfortran} option
2735 to link with the Fortran library. If your main program is written in
2736 C or some other language instead of Fortran, see
2737 @ref{Non-Fortran Main Program}, below.
2739 @node Interoperability with C
2740 @section Interoperability with C
2741 @cindex interoperability with C
2742 @cindex C interoperability
2746 * Derived Types and struct::
2747 * Interoperable Global Variables::
2748 * Interoperable Subroutines and Functions::
2749 * Working with C Pointers::
2750 * Further Interoperability of Fortran with C::
2753 Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a
2754 standardized way to generate procedure and derived-type
2755 declarations and global variables that are interoperable with C
2756 (ISO/IEC 9899:1999). The @code{BIND(C)} attribute has been added
2757 to inform the compiler that a symbol shall be interoperable with C;
2758 also, some constraints are added. Note, however, that not
2759 all C features have a Fortran equivalent or vice versa. For instance,
2760 neither C's unsigned integers nor C's functions with variable number
2761 of arguments have an equivalent in Fortran.
2763 Note that array dimensions are reversely ordered in C and that arrays in
2764 C always start with index 0 while in Fortran they start by default with
2765 1. Thus, an array declaration @code{A(n,m)} in Fortran matches
2766 @code{A[m][n]} in C and accessing the element @code{A(i,j)} matches
2767 @code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]};
2768 assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}).
2770 @node Intrinsic Types
2771 @subsection Intrinsic Types
2772 @cindex C intrinsic type interoperability
2773 @cindex intrinsic type interoperability with C
2774 @cindex interoperability, intrinsic type
2776 In order to ensure that exactly the same variable type and kind is used
2777 in C and Fortran, you should use the named constants for kind parameters
2778 that are defined in the @code{ISO_C_BINDING} intrinsic module.
2779 That module contains named constants of character type representing
2780 the escaped special characters in C, such as newline.
2781 For a list of the constants, see @ref{ISO_C_BINDING}.
2783 For logical types, please note that the Fortran standard only guarantees
2784 interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
2785 logicals and C99 defines that @code{true} has the value 1 and @code{false}
2786 the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL}
2787 (with any kind parameter) gives an undefined result. (Passing other integer
2788 values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the
2789 integer is explicitly or implicitly casted to @code{_Bool}.)
2791 @node Derived Types and struct
2792 @subsection Derived Types and struct
2793 @cindex C derived type and struct interoperability
2794 @cindex derived type interoperability with C
2795 @cindex interoperability, derived type and struct
2797 For compatibility of derived types with @code{struct}, use
2798 the @code{BIND(C)} attribute in the type declaration. For instance, the
2799 following type declaration
2803 TYPE, BIND(C) :: myType
2804 INTEGER(C_INT) :: i1, i2
2805 INTEGER(C_SIGNED_CHAR) :: i3
2806 REAL(C_DOUBLE) :: d1
2807 COMPLEX(C_FLOAT_COMPLEX) :: c1
2808 CHARACTER(KIND=C_CHAR) :: str(5)
2813 matches the following @code{struct} declaration in C
2818 /* Note: "char" might be signed or unsigned. */
2826 Derived types with the C binding attribute shall not have the @code{sequence}
2827 attribute, type parameters, the @code{extends} attribute, nor type-bound
2828 procedures. Every component must be of interoperable type and kind and may not
2829 have the @code{pointer} or @code{allocatable} attribute. The names of the
2830 components are irrelevant for interoperability.
2832 As there exist no direct Fortran equivalents, neither unions nor structs
2833 with bit field or variable-length array members are interoperable.
2835 @node Interoperable Global Variables
2836 @subsection Interoperable Global Variables
2837 @cindex C variable interoperability
2838 @cindex variable interoperability with C
2839 @cindex interoperability, variable
2841 Variables can be made accessible from C using the C binding attribute,
2842 optionally together with specifying a binding name. Those variables
2843 have to be declared in the declaration part of a @code{MODULE},
2844 be of interoperable type, and have neither the @code{pointer} nor
2845 the @code{allocatable} attribute.
2851 integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag
2852 type(myType), bind(C) :: tp
2856 Here, @code{_MyProject_flags} is the case-sensitive name of the variable
2857 as seen from C programs while @code{global_flag} is the case-insensitive
2858 name as seen from Fortran. If no binding name is specified, as for
2859 @var{tp}, the C binding name is the (lowercase) Fortran binding name.
2860 If a binding name is specified, only a single variable may be after the
2861 double colon. Note of warning: You cannot use a global variable to
2862 access @var{errno} of the C library as the C standard allows it to be
2863 a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead.
2865 @node Interoperable Subroutines and Functions
2866 @subsection Interoperable Subroutines and Functions
2867 @cindex C procedure interoperability
2868 @cindex procedure interoperability with C
2869 @cindex function interoperability with C
2870 @cindex subroutine interoperability with C
2871 @cindex interoperability, subroutine and function
2873 Subroutines and functions have to have the @code{BIND(C)} attribute to
2874 be compatible with C. The dummy argument declaration is relatively
2875 straightforward. However, one needs to be careful because C uses
2876 call-by-value by default while Fortran behaves usually similar to
2877 call-by-reference. Furthermore, strings and pointers are handled
2880 To pass a variable by value, use the @code{VALUE} attribute.
2881 Thus, the following C prototype
2884 @code{int func(int i, int *j)}
2888 matches the Fortran declaration
2891 integer(c_int) function func(i,j)
2892 use iso_c_binding, only: c_int
2893 integer(c_int), VALUE :: i
2897 Note that pointer arguments also frequently need the @code{VALUE} attribute,
2898 see @ref{Working with C Pointers}.
2900 Strings are handled quite differently in C and Fortran. In C a string
2901 is a @code{NUL}-terminated array of characters while in Fortran each string
2902 has a length associated with it and is thus not terminated (by e.g.
2903 @code{NUL}). For example, if you want to use the following C function,
2907 void print_C(char *string) /* equivalent: char string[] */
2909 printf("%s\n", string);
2914 to print ``Hello World'' from Fortran, you can call it using
2917 use iso_c_binding, only: C_CHAR, C_NULL_CHAR
2919 subroutine print_c(string) bind(C, name="print_C")
2920 use iso_c_binding, only: c_char
2921 character(kind=c_char) :: string(*)
2922 end subroutine print_c
2924 call print_c(C_CHAR_"Hello World"//C_NULL_CHAR)
2927 As the example shows, you need to ensure that the
2928 string is @code{NUL} terminated. Additionally, the dummy argument
2929 @var{string} of @code{print_C} is a length-one assumed-size
2930 array; using @code{character(len=*)} is not allowed. The example
2931 above uses @code{c_char_"Hello World"} to ensure the string
2932 literal has the right type; typically the default character
2933 kind and @code{c_char} are the same and thus @code{"Hello World"}
2934 is equivalent. However, the standard does not guarantee this.
2936 The use of strings is now further illustrated using the C library
2937 function @code{strncpy}, whose prototype is
2940 char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
2944 The function @code{strncpy} copies at most @var{n} characters from
2945 string @var{s2} to @var{s1} and returns @var{s1}. In the following
2946 example, we ignore the return value:
2951 character(len=30) :: str,str2
2953 ! Ignore the return value of strncpy -> subroutine
2954 ! "restrict" is always assumed if we do not pass a pointer
2955 subroutine strncpy(dest, src, n) bind(C)
2957 character(kind=c_char), intent(out) :: dest(*)
2958 character(kind=c_char), intent(in) :: src(*)
2959 integer(c_size_t), value, intent(in) :: n
2960 end subroutine strncpy
2962 str = repeat('X',30) ! Initialize whole string with 'X'
2963 call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, &
2964 len(c_char_"Hello World",kind=c_size_t))
2965 print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX"
2969 The intrinsic procedures are described in @ref{Intrinsic Procedures}.
2971 @node Working with C Pointers
2972 @subsection Working with C Pointers
2976 C pointers are represented in Fortran via the special opaque derived
2977 type @code{type(c_ptr)} (with private components). C pointers are distinct
2978 from Fortran objects with the @code{POINTER} attribute. Thus one needs to
2979 use intrinsic conversion procedures to convert from or to C pointers.
2980 For some applications, using an assumed type (@code{TYPE(*)}) can be
2981 an alternative to a C pointer, and you can also use library routines
2982 to access Fortran pointers from C. See @ref{Further Interoperability
2985 Here is an example of using C pointers in Fortran:
2989 type(c_ptr) :: cptr1, cptr2
2990 integer, target :: array(7), scalar
2991 integer, pointer :: pa(:), ps
2992 cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the
2993 ! array is contiguous if required by the C
2995 cptr2 = c_loc(scalar)
2996 call c_f_pointer(cptr2, ps)
2997 call c_f_pointer(cptr2, pa, shape=[7])
3000 When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument
3003 If a pointer is a dummy argument of an interoperable procedure, it usually
3004 has to be declared using the @code{VALUE} attribute. @code{void*}
3005 matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone
3006 matches @code{void**}.
3008 Procedure pointers are handled analogously to pointers; the C type is
3009 @code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are
3010 @code{C_F_PROCPOINTER} and @code{C_FUNLOC}.
3012 Let us consider two examples of actually passing a procedure pointer from
3013 C to Fortran and vice versa. Note that these examples are also very
3014 similar to passing ordinary pointers between both languages. First,
3015 consider this code in C:
3018 /* Procedure implemented in Fortran. */
3019 void get_values (void (*)(double));
3021 /* Call-back routine we want called from Fortran. */
3025 printf ("Number is %f.\n", x);
3028 /* Call Fortran routine and pass call-back to it. */
3032 get_values (&print_it);
3036 A matching implementation for @code{get_values} in Fortran, that correctly
3037 receives the procedure pointer from C and is able to call it, is given
3038 in the following @code{MODULE}:
3044 ! Define interface of call-back routine.
3046 SUBROUTINE callback (x)
3047 USE, INTRINSIC :: ISO_C_BINDING
3048 REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x
3049 END SUBROUTINE callback
3054 ! Define C-bound procedure.
3055 SUBROUTINE get_values (cproc) BIND(C)
3056 USE, INTRINSIC :: ISO_C_BINDING
3057 TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc
3059 PROCEDURE(callback), POINTER :: proc
3061 ! Convert C to Fortran procedure pointer.
3062 CALL C_F_PROCPOINTER (cproc, proc)
3065 CALL proc (1.0_C_DOUBLE)
3066 CALL proc (-42.0_C_DOUBLE)
3067 CALL proc (18.12_C_DOUBLE)
3068 END SUBROUTINE get_values
3073 Next, we want to call a C routine that expects a procedure pointer argument
3074 and pass it a Fortran procedure (which clearly must be interoperable!).
3075 Again, the C function may be:
3079 call_it (int (*func)(int), int arg)
3085 It can be used as in the following Fortran code:
3089 USE, INTRINSIC :: ISO_C_BINDING
3092 ! Define interface of C function.
3094 INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C)
3095 USE, INTRINSIC :: ISO_C_BINDING
3096 TYPE(C_FUNPTR), INTENT(IN), VALUE :: func
3097 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
3098 END FUNCTION call_it
3103 ! Define procedure passed to C function.
3104 ! It must be interoperable!
3105 INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C)
3106 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
3107 double_it = arg + arg
3108 END FUNCTION double_it
3111 SUBROUTINE foobar ()
3112 TYPE(C_FUNPTR) :: cproc
3113 INTEGER(KIND=C_INT) :: i
3115 ! Get C procedure pointer.
3116 cproc = C_FUNLOC (double_it)
3119 DO i = 1_C_INT, 10_C_INT
3120 PRINT *, call_it (cproc, i)
3122 END SUBROUTINE foobar
3127 @node Further Interoperability of Fortran with C
3128 @subsection Further Interoperability of Fortran with C
3129 @cindex Further Interoperability of Fortran with C
3131 @cindex array descriptor
3133 @cindex assumed-type
3134 @cindex assumed-rank
3136 GNU Fortran implements the Technical Specification ISO/IEC TS
3137 29113:2012, which extends the interoperability support of Fortran 2003
3138 and Fortran 2008 and is now part of the 2018 Fortran standard.
3139 Besides removing some restrictions and constraints, the Technical
3140 Specification adds assumed-type (@code{TYPE(*)}) and assumed-rank
3141 (@code{DIMENSION(..)}) variables and allows for interoperability of
3142 assumed-shape, assumed-rank, and deferred-shape arrays, as well as
3143 allocatables and pointers. Objects of these types are passed to
3144 @code{BIND(C)} functions as descriptors with a standard interface,
3145 declared in the header file @code{<ISO_Fortran_binding.h>}.
3147 Note: Currently, GNU Fortran does not use internally the array descriptor
3148 (dope vector) as specified in the Technical Specification, but uses
3149 an array descriptor with different fields in functions without the
3150 @code{BIND(C)} attribute. Arguments to functions marked @code{BIND(C)}
3151 are converted to the specified form. If you need to access GNU Fortran's
3152 internal array descriptor, you can use the Chasm Language Interoperability
3153 Tools, @url{http://chasm-interop.sourceforge.net/}.
3155 @node GNU Fortran Compiler Directives
3156 @section GNU Fortran Compiler Directives
3159 * ATTRIBUTES directive::
3160 * UNROLL directive::
3161 * BUILTIN directive::
3163 * VECTOR directive::
3164 * NOVECTOR directive::
3167 @node ATTRIBUTES directive
3168 @subsection ATTRIBUTES directive
3170 The Fortran standard describes how a conforming program shall
3171 behave; however, the exact implementation is not standardized. In order
3172 to allow the user to choose specific implementation details, compiler
3173 directives can be used to set attributes of variables and procedures
3174 which are not part of the standard. Whether a given attribute is
3175 supported and its exact effects depend on both the operating system and
3176 on the processor; see
3177 @ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)}
3180 For procedures and procedure pointers, the following attributes can
3181 be used to change the calling convention:
3184 @item @code{CDECL} -- standard C calling convention
3185 @item @code{STDCALL} -- convention where the called procedure pops the stack
3186 @item @code{FASTCALL} -- part of the arguments are passed via registers
3187 instead using the stack
3190 Besides changing the calling convention, the attributes also influence
3191 the decoration of the symbol name, e.g., by a leading underscore or by
3192 a trailing at-sign followed by the number of bytes on the stack. When
3193 assigning a procedure to a procedure pointer, both should use the same
3196 On some systems, procedures and global variables (module variables and
3197 @code{COMMON} blocks) need special handling to be accessible when they
3198 are in a shared library. The following attributes are available:
3201 @item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL
3202 @item @code{DLLIMPORT} -- reference the function or variable using a
3206 For dummy arguments, the @code{NO_ARG_CHECK} attribute can be used; in
3207 other compilers, it is also known as @code{IGNORE_TKR}. For dummy arguments
3208 with this attribute actual arguments of any type and kind (similar to
3209 @code{TYPE(*)}), scalars and arrays of any rank (no equivalent
3210 in Fortran standard) are accepted. As with @code{TYPE(*)}, the argument
3211 is unlimited polymorphic and no type information is available.
3212 Additionally, the argument may only be passed to dummy arguments
3213 with the @code{NO_ARG_CHECK} attribute and as argument to the
3214 @code{PRESENT} intrinsic function and to @code{C_LOC} of the
3215 @code{ISO_C_BINDING} module.
3217 Variables with @code{NO_ARG_CHECK} attribute shall be of assumed-type
3218 (@code{TYPE(*)}; recommended) or of type @code{INTEGER}, @code{LOGICAL},
3219 @code{REAL} or @code{COMPLEX}. They shall not have the @code{ALLOCATE},
3220 @code{CODIMENSION}, @code{INTENT(OUT)}, @code{POINTER} or @code{VALUE}
3221 attribute; furthermore, they shall be either scalar or of assumed-size
3222 (@code{dimension(*)}). As @code{TYPE(*)}, the @code{NO_ARG_CHECK} attribute
3223 requires an explicit interface.
3226 @item @code{NO_ARG_CHECK} -- disable the type, kind and rank checking
3227 @item @code{DEPRECATED} -- print a warning when using a such-tagged
3228 deprecated procedure, variable or parameter; the warning can be suppressed
3229 with @option{-Wno-deprecated-declarations}.
3230 @item @code{NOINLINE} -- prevent inlining given function.
3231 @item @code{NORETURN} -- add a hint that a given function cannot return.
3232 @item @code{WEAK} -- emit the declaration of an external symbol as a weak
3233 symbol rather than a global. This is primarily useful in defining library
3234 functions that can be overridden in user code, though it can also be used with
3235 non-function declarations. The overriding symbol must have the same type as
3240 The attributes are specified using the syntax
3242 @code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list}
3244 where in free-form source code only whitespace is allowed before @code{!GCC$}
3245 and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall
3246 start in the first column.
3248 For procedures, the compiler directives shall be placed into the body
3249 of the procedure; for variables and procedure pointers, they shall be in
3250 the same declaration part as the variable or procedure pointer.
3253 @node UNROLL directive
3254 @subsection UNROLL directive
3256 The syntax of the directive is
3258 @code{!GCC$ unroll N}
3260 You can use this directive to control how many times a loop should be unrolled.
3261 It must be placed immediately before a @code{DO} loop and applies only to the
3262 loop that follows. N is an integer constant specifying the unrolling factor.
3263 The values of 0 and 1 block any unrolling of the loop.
3265 For @code{DO CONCURRENT} constructs the unrolling specification applies
3266 only to the first loop control variable.
3269 @node BUILTIN directive
3270 @subsection BUILTIN directive
3272 The syntax of the directive is
3274 @code{!GCC$ BUILTIN (B) attributes simd FLAGS IF('target')}
3276 You can use this directive to define which middle-end built-ins provide vector
3277 implementations. @code{B} is name of the middle-end built-in. @code{FLAGS}
3278 are optional and must be either "(inbranch)" or "(notinbranch)".
3279 @code{IF} statement is optional and is used to filter multilib ABIs
3280 for the built-in that should be vectorized. Example usage:
3283 !GCC$ builtin (sinf) attributes simd (notinbranch) if('x86_64')
3286 The purpose of the directive is to provide an API among the GCC compiler and
3287 the GNU C Library which would define vector implementations of math routines.
3290 @node IVDEP directive
3291 @subsection IVDEP directive
3293 The syntax of the directive is
3297 This directive tells the compiler to ignore vector dependencies in the
3298 following loop. It must be placed immediately before a @code{DO} loop
3299 and applies only to the loop that follows.
3301 Sometimes the compiler may not have sufficient information to decide
3302 whether a particular loop is vectorizable due to potential
3303 dependencies between iterations. The purpose of the directive is to
3304 tell the compiler that vectorization is safe.
3306 For @code{DO CONCURRENT} constructs this annotation is implicit to all
3307 loop control variables.
3309 This directive is intended for annotation of existing code. For new
3310 code it is recommended to consider OpenMP SIMD directives as potential
3314 @node VECTOR directive
3315 @subsection VECTOR directive
3317 The syntax of the directive is
3321 This directive tells the compiler to vectorize the following loop. It
3322 must be placed immediately before a @code{DO} loop and applies only to
3323 the loop that follows.
3325 For @code{DO CONCURRENT} constructs this annotation applies to all loops
3326 specified in the concurrent header.
3329 @node NOVECTOR directive
3330 @subsection NOVECTOR directive
3332 The syntax of the directive is
3334 @code{!GCC$ novector}
3336 This directive tells the compiler to not vectorize the following loop.
3337 It must be placed immediately before a @code{DO} loop and applies only
3338 to the loop that follows.
3340 For @code{DO CONCURRENT} constructs this annotation applies to all loops
3341 specified in the concurrent header.
3344 @node Non-Fortran Main Program
3345 @section Non-Fortran Main Program
3348 * _gfortran_set_args:: Save command-line arguments
3349 * _gfortran_set_options:: Set library option flags
3350 * _gfortran_set_convert:: Set endian conversion
3351 * _gfortran_set_record_marker:: Set length of record markers
3352 * _gfortran_set_fpe:: Set when a Floating Point Exception should be raised
3353 * _gfortran_set_max_subrecord_length:: Set subrecord length
3356 Even if you are doing mixed-language programming, it is very
3357 likely that you do not need to know or use the information in this
3358 section. Since it is about the internal structure of GNU Fortran,
3359 it may also change in GCC minor releases.
3361 When you compile a @code{PROGRAM} with GNU Fortran, a function
3362 with the name @code{main} (in the symbol table of the object file)
3363 is generated, which initializes the libgfortran library and then
3364 calls the actual program which uses the name @code{MAIN__}, for
3365 historic reasons. If you link GNU Fortran compiled procedures
3366 to, e.g., a C or C++ program or to a Fortran program compiled by
3367 a different compiler, the libgfortran library is not initialized
3368 and thus a few intrinsic procedures do not work properly, e.g.
3369 those for obtaining the command-line arguments.
3371 Therefore, if your @code{PROGRAM} is not compiled with
3372 GNU Fortran and the GNU Fortran compiled procedures require
3373 intrinsics relying on the library initialization, you need to
3374 initialize the library yourself. Using the default options,
3375 gfortran calls @code{_gfortran_set_args} and
3376 @code{_gfortran_set_options}. The initialization of the former
3377 is needed if the called procedures access the command line
3378 (and for backtracing); the latter sets some flags based on the
3379 standard chosen or to enable backtracing. In typical programs,
3380 it is not necessary to call any initialization function.
3382 If your @code{PROGRAM} is compiled with GNU Fortran, you shall
3383 not call any of the following functions. The libgfortran
3384 initialization functions are shown in C syntax but using C
3385 bindings they are also accessible from Fortran.
3388 @node _gfortran_set_args
3389 @subsection @code{_gfortran_set_args} --- Save command-line arguments
3390 @fnindex _gfortran_set_args
3391 @cindex libgfortran initialization, set_args
3394 @item @emph{Description}:
3395 @code{_gfortran_set_args} saves the command-line arguments; this
3396 initialization is required if any of the command-line intrinsics
3397 is called. Additionally, it shall be called if backtracing is
3398 enabled (see @code{_gfortran_set_options}).
3400 @item @emph{Syntax}:
3401 @code{void _gfortran_set_args (int argc, char *argv[])}
3403 @item @emph{Arguments}:
3404 @multitable @columnfractions .15 .70
3405 @item @var{argc} @tab number of command line argument strings
3406 @item @var{argv} @tab the command-line argument strings; argv[0]
3407 is the pathname of the executable itself.
3410 @item @emph{Example}:
3412 int main (int argc, char *argv[])
3414 /* Initialize libgfortran. */
3415 _gfortran_set_args (argc, argv);
3422 @node _gfortran_set_options
3423 @subsection @code{_gfortran_set_options} --- Set library option flags
3424 @fnindex _gfortran_set_options
3425 @cindex libgfortran initialization, set_options
3428 @item @emph{Description}:
3429 @code{_gfortran_set_options} sets several flags related to the Fortran
3430 standard to be used, whether backtracing should be enabled
3431 and whether range checks should be performed. The syntax allows for
3432 upward compatibility since the number of passed flags is specified; for
3433 non-passed flags, the default value is used. See also
3434 @pxref{Code Gen Options}. Please note that not all flags are actually
3437 @item @emph{Syntax}:
3438 @code{void _gfortran_set_options (int num, int options[])}
3440 @item @emph{Arguments}:
3441 @multitable @columnfractions .15 .70
3442 @item @var{num} @tab number of options passed
3443 @item @var{argv} @tab The list of flag values
3446 @item @emph{option flag list}:
3447 @multitable @columnfractions .15 .70
3448 @item @var{option}[0] @tab Allowed standard; can give run-time errors
3449 if e.g. an input-output edit descriptor is invalid in a given
3450 standard. Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1),
3451 @code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4),
3452 @code{GFC_STD_F95} (8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU}
3453 (32), @code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128),
3454 @code{GFC_STD_F2008_OBS} (256), @code{GFC_STD_F2018} (512),
3455 @code{GFC_STD_F2018_OBS} (1024), @code{GFC_STD_F2018_DEL} (2048),
3456 @code{GFC_STD_F2023} (4096), and @code{GFC_STD_F2023_DEL} (8192).
3457 Default: @code{GFC_STD_F95_OBS | GFC_STD_F95_DEL | GFC_STD_F95 |
3458 GFC_STD_F2003 | GFC_STD_F2008 | GFC_STD_F2008_OBS
3459 | GFC_STD_F77 | GFC_STD_F2018 | GFC_STD_F2018_OBS | GFC_STD_F2018_DEL
3460 | GFC_STD_F2023 | GFC_STD_F2023_DEL | GFC_STD_GNU | GFC_STD_LEGACY}.
3461 @item @var{option}[1] @tab Standard-warning flag; prints a warning to
3462 standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}.
3463 @item @var{option}[2] @tab If non zero, enable pedantic checking.
3465 @item @var{option}[3] @tab Unused.
3466 @item @var{option}[4] @tab If non zero, enable backtracing on run-time
3467 errors. Default: off. (Default in the compiler: on.)
3468 Note: Installs a signal handler and requires command-line
3469 initialization using @code{_gfortran_set_args}.
3470 @item @var{option}[5] @tab If non zero, supports signed zeros.
3472 @item @var{option}[6] @tab Enables run-time checking. Possible values
3473 are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2),
3474 GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (8), GFC_RTCHECK_POINTER (16),
3475 GFC_RTCHECK_MEM (32), GFC_RTCHECK_BITS (64).
3477 @item @var{option}[7] @tab Unused.
3478 @item @var{option}[8] @tab Show a warning when invoking @code{STOP} and
3479 @code{ERROR STOP} if a floating-point exception occurred. Possible values
3480 are (bitwise or-ed) @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3481 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3482 @code{GFC_FPE_UNDERFLOW} (16), @code{GFC_FPE_INEXACT} (32). Default: None (0).
3483 (Default in the compiler: @code{GFC_FPE_INVALID | GFC_FPE_DENORMAL |
3484 GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW}.)
3487 @item @emph{Example}:
3489 /* Use gfortran 4.9 default options. */
3490 static int options[] = @{68, 511, 0, 0, 1, 1, 0, 0, 31@};
3491 _gfortran_set_options (9, &options);
3496 @node _gfortran_set_convert
3497 @subsection @code{_gfortran_set_convert} --- Set endian conversion
3498 @fnindex _gfortran_set_convert
3499 @cindex libgfortran initialization, set_convert
3502 @item @emph{Description}:
3503 @code{_gfortran_set_convert} set the representation of data for
3506 @item @emph{Syntax}:
3507 @code{void _gfortran_set_convert (int conv)}
3509 @item @emph{Arguments}:
3510 @multitable @columnfractions .15 .70
3511 @item @var{conv} @tab Endian conversion, possible values:
3512 GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1),
3513 GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3).
3516 @item @emph{Example}:
3518 int main (int argc, char *argv[])
3520 /* Initialize libgfortran. */
3521 _gfortran_set_args (argc, argv);
3522 _gfortran_set_convert (1);
3529 @node _gfortran_set_record_marker
3530 @subsection @code{_gfortran_set_record_marker} --- Set length of record markers
3531 @fnindex _gfortran_set_record_marker
3532 @cindex libgfortran initialization, set_record_marker
3535 @item @emph{Description}:
3536 @code{_gfortran_set_record_marker} sets the length of record markers
3537 for unformatted files.
3539 @item @emph{Syntax}:
3540 @code{void _gfortran_set_record_marker (int val)}
3542 @item @emph{Arguments}:
3543 @multitable @columnfractions .15 .70
3544 @item @var{val} @tab Length of the record marker; valid values
3545 are 4 and 8. Default is 4.
3548 @item @emph{Example}:
3550 int main (int argc, char *argv[])
3552 /* Initialize libgfortran. */
3553 _gfortran_set_args (argc, argv);
3554 _gfortran_set_record_marker (8);
3561 @node _gfortran_set_fpe
3562 @subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps
3563 @fnindex _gfortran_set_fpe
3564 @cindex libgfortran initialization, set_fpe
3567 @item @emph{Description}:
3568 @code{_gfortran_set_fpe} enables floating point exception traps for
3569 the specified exceptions. On most systems, this will result in a
3570 SIGFPE signal being sent and the program being aborted.
3572 @item @emph{Syntax}:
3573 @code{void _gfortran_set_fpe (int val)}
3575 @item @emph{Arguments}:
3576 @multitable @columnfractions .15 .70
3577 @item @var{option}[0] @tab IEEE exceptions. Possible values are
3578 (bitwise or-ed) zero (0, default) no trapping,
3579 @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3580 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3581 @code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32).
3584 @item @emph{Example}:
3586 int main (int argc, char *argv[])
3588 /* Initialize libgfortran. */
3589 _gfortran_set_args (argc, argv);
3590 /* FPE for invalid operations such as SQRT(-1.0). */
3591 _gfortran_set_fpe (1);
3598 @node _gfortran_set_max_subrecord_length
3599 @subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length
3600 @fnindex _gfortran_set_max_subrecord_length
3601 @cindex libgfortran initialization, set_max_subrecord_length
3604 @item @emph{Description}:
3605 @code{_gfortran_set_max_subrecord_length} set the maximum length
3606 for a subrecord. This option only makes sense for testing and
3607 debugging of unformatted I/O.
3609 @item @emph{Syntax}:
3610 @code{void _gfortran_set_max_subrecord_length (int val)}
3612 @item @emph{Arguments}:
3613 @multitable @columnfractions .15 .70
3614 @item @var{val} @tab the maximum length for a subrecord;
3615 the maximum permitted value is 2147483639, which is also
3619 @item @emph{Example}:
3621 int main (int argc, char *argv[])
3623 /* Initialize libgfortran. */
3624 _gfortran_set_args (argc, argv);
3625 _gfortran_set_max_subrecord_length (8);
3632 @node Naming and argument-passing conventions
3633 @section Naming and argument-passing conventions
3635 This section gives an overview about the naming convention of procedures
3636 and global variables and about the argument passing conventions used by
3637 GNU Fortran. If a C binding has been specified, the naming convention
3638 and some of the argument-passing conventions change. If possible,
3639 mixed-language and mixed-compiler projects should use the better defined
3640 C binding for interoperability. See @pxref{Interoperability with C}.
3643 * Naming conventions::
3644 * Argument passing conventions::
3648 @node Naming conventions
3649 @subsection Naming conventions
3651 According the Fortran standard, valid Fortran names consist of a letter
3652 between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0},
3653 @code{1} to @code{9} and underscores (@code{_}) with the restriction
3654 that names may only start with a letter. As vendor extension, the
3655 dollar sign (@code{$}) is additionally permitted with the option
3656 @option{-fdollar-ok}, but not as first character and only if the
3657 target system supports it.
3659 By default, the procedure name is the lower-cased Fortran name with an
3660 appended underscore (@code{_}); using @option{-fno-underscoring} no
3661 underscore is appended while @code{-fsecond-underscore} appends two
3662 underscores. Depending on the target system and the calling convention,
3663 the procedure might be additionally dressed; for instance, on 32bit
3664 Windows with @code{stdcall}, an at-sign @code{@@} followed by an integer
3665 number is appended. For the changing the calling convention, see
3666 @pxref{GNU Fortran Compiler Directives}.
3668 For common blocks, the same convention is used, i.e. by default an
3669 underscore is appended to the lower-cased Fortran name. Blank commons
3670 have the name @code{__BLNK__}.
3672 For procedures and variables declared in the specification space of a
3673 module, the name is formed by @code{__}, followed by the lower-cased
3674 module name, @code{_MOD_}, and the lower-cased Fortran name. Note that
3675 no underscore is appended.
3678 @node Argument passing conventions
3679 @subsection Argument passing conventions
3681 Subroutines do not return a value (matching C99's @code{void}) while
3682 functions either return a value as specified in the platform ABI or
3683 the result variable is passed as hidden argument to the function and
3684 no result is returned. A hidden result variable is used when the
3685 result variable is an array or of type @code{CHARACTER}.
3687 Arguments are passed according to the platform ABI. In particular,
3688 complex arguments might not be compatible to a struct with two real
3689 components for the real and imaginary part. The argument passing
3690 matches the one of C99's @code{_Complex}. Functions with scalar
3691 complex result variables return their value and do not use a
3692 by-reference argument. Note that with the @option{-ff2c} option,
3693 the argument passing is modified and no longer completely matches
3694 the platform ABI. Some other Fortran compilers use @code{f2c}
3695 semantic by default; this might cause problems with
3698 GNU Fortran passes most arguments by reference, i.e. by passing a
3699 pointer to the data. Note that the compiler might use a temporary
3700 variable into which the actual argument has been copied, if required
3701 semantically (copy-in/copy-out).
3703 For arguments with @code{ALLOCATABLE} and @code{POINTER}
3704 attribute (including procedure pointers), a pointer to the pointer
3705 is passed such that the pointer address can be modified in the
3708 For dummy arguments with the @code{VALUE} attribute: Scalar arguments
3709 of the type @code{INTEGER}, @code{LOGICAL}, @code{REAL} and
3710 @code{COMPLEX} are passed by value according to the platform ABI.
3711 (As vendor extension and not recommended, using @code{%VAL()} in the
3712 call to a procedure has the same effect.) For @code{TYPE(C_PTR)} and
3713 procedure pointers, the pointer itself is passed such that it can be
3714 modified without affecting the caller.
3715 @c FIXME: Document how VALUE is handled for CHARACTER, TYPE,
3716 @c CLASS and arrays, i.e. whether the copy-in is done in the caller
3717 @c or in the callee.
3719 For Boolean (@code{LOGICAL}) arguments, please note that GCC expects
3720 only the integer value 0 and 1. If a GNU Fortran @code{LOGICAL}
3721 variable contains another integer value, the result is undefined.
3722 As some other Fortran compilers use @math{-1} for @code{.TRUE.},
3723 extra care has to be taken -- such as passing the value as
3724 @code{INTEGER}. (The same value restriction also applies to other
3725 front ends of GCC, e.g. to GCC's C99 compiler for @code{_Bool}
3726 or GCC's Ada compiler for @code{Boolean}.)
3728 For arguments of @code{CHARACTER} type, the character length is passed
3729 as a hidden argument at the end of the argument list, except when the
3730 corresponding dummy argument is declared as @code{TYPE(*)}. For
3731 deferred-length strings, the value is passed by reference, otherwise
3732 by value. The character length has the C type @code{size_t} (or
3733 @code{INTEGER(kind=C_SIZE_T)} in Fortran). Note that this is
3734 different to older versions of the GNU Fortran compiler, where the
3735 type of the hidden character length argument was a C @code{int}. In
3736 order to retain compatibility with older versions, one can e.g. for
3737 the following Fortran procedure
3740 subroutine fstrlen (s, a)
3741 character(len=*) :: s
3744 end subroutine fstrlen
3747 define the corresponding C prototype as follows:
3751 typedef size_t fortran_charlen_t;
3753 typedef int fortran_charlen_t;
3756 void fstrlen_ (char*, int*, fortran_charlen_t);
3759 In order to avoid such compiler-specific details, for new code it is
3760 instead recommended to use the ISO_C_BINDING feature.
3762 Note with C binding, @code{CHARACTER(len=1)} result variables are
3763 returned according to the platform ABI and no hidden length argument
3764 is used for dummy arguments; with @code{VALUE}, those variables are
3767 For @code{OPTIONAL} dummy arguments, an absent argument is denoted
3768 by a NULL pointer, except for scalar dummy arguments of intrinsic type
3769 which have the @code{VALUE} attribute. For those, a hidden Boolean
3770 argument (@code{logical(kind=C_bool),value}) is used to indicate
3771 whether the argument is present.
3773 Arguments which are assumed-shape, assumed-rank or deferred-rank
3774 arrays or, with @option{-fcoarray=lib}, allocatable scalar coarrays use
3775 an array descriptor. All other arrays pass the address of the
3776 first element of the array. With @option{-fcoarray=lib}, the token
3777 and the offset belonging to nonallocatable coarrays dummy arguments
3778 are passed as hidden argument along the character length hidden
3779 arguments. The token is an opaque pointer identifying the coarray
3780 and the offset is a passed-by-value integer of kind @code{C_PTRDIFF_T},
3781 denoting the byte offset between the base address of the coarray and
3782 the passed scalar or first element of the passed array.
3784 The arguments are passed in the following order
3786 @item Result variable, when the function result is passed by reference
3787 @item Character length of the function result, if it is a of type
3788 @code{CHARACTER} and no C binding is used
3789 @item The arguments in the order in which they appear in the Fortran
3791 @item The present status for optional arguments with value attribute,
3792 which are internally passed by value
3793 @item The character length and/or coarray token and offset for the first
3794 argument which is a @code{CHARACTER} or a nonallocatable coarray dummy
3795 argument, followed by the hidden arguments of the next dummy argument
3800 @c ---------------------------------------------------------------------
3801 @c Coarray Programming
3802 @c ---------------------------------------------------------------------
3804 @node Coarray Programming
3805 @chapter Coarray Programming
3809 * Type and enum ABI Documentation::
3810 * Function ABI Documentation::
3814 @node Type and enum ABI Documentation
3815 @section Type and enum ABI Documentation
3820 * caf_deregister_t::
3826 @subsection @code{caf_token_t}
3828 Typedef of type @code{void *} on the compiler side. Can be any data
3829 type on the library side.
3831 @node caf_register_t
3832 @subsection @code{caf_register_t}
3834 Indicates which kind of coarray variable should be registered.
3837 typedef enum caf_register_t {
3838 CAF_REGTYPE_COARRAY_STATIC,
3839 CAF_REGTYPE_COARRAY_ALLOC,
3840 CAF_REGTYPE_LOCK_STATIC,
3841 CAF_REGTYPE_LOCK_ALLOC,
3842 CAF_REGTYPE_CRITICAL,
3843 CAF_REGTYPE_EVENT_STATIC,
3844 CAF_REGTYPE_EVENT_ALLOC,
3845 CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY,
3846 CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY
3851 The values @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and
3852 @code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} are for allocatable components
3853 in derived type coarrays only. The first one sets up the token without
3854 allocating memory for allocatable component. The latter one only allocates the
3855 memory for an allocatable component in a derived type coarray. The token
3856 needs to be setup previously by the REGISTER_ONLY. This allows to have
3857 allocatable components un-allocated on some images. The status whether an
3858 allocatable component is allocated on a remote image can be queried by
3859 @code{_caf_is_present} which used internally by the @code{ALLOCATED}
3862 @node caf_deregister_t
3863 @subsection @code{caf_deregister_t}
3866 typedef enum caf_deregister_t {
3867 CAF_DEREGTYPE_COARRAY_DEREGISTER,
3868 CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY
3873 Allows to specify the type of deregistration of a coarray object. The
3874 @code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} flag is only allowed for
3875 allocatable components in derived type coarrays.
3877 @node caf_reference_t
3878 @subsection @code{caf_reference_t}
3880 The structure used for implementing arbitrary reference chains.
3881 A @code{CAF_REFERENCE_T} allows to specify a component reference or any kind
3882 of array reference of any rank supported by gfortran. For array references all
3883 kinds as known by the compiler/Fortran standard are supported indicated by
3887 typedef enum caf_ref_type_t {
3888 /* Reference a component of a derived type, either regular one or an
3889 allocatable or pointer type. For regular ones idx in caf_reference_t is
3892 /* Reference an allocatable array. */
3894 /* Reference a non-allocatable/non-pointer array. I.e., the coarray object
3895 has no array descriptor associated and the addressing is done
3896 completely using the ref. */
3897 CAF_REF_STATIC_ARRAY
3902 typedef enum caf_array_ref_t {
3903 /* No array ref. This terminates the array ref. */
3904 CAF_ARR_REF_NONE = 0,
3905 /* Reference array elements given by a vector. Only for this mode
3906 caf_reference_t.u.a.dim[i].v is valid. */
3908 /* A full array ref (:). */
3910 /* Reference a range on elements given by start, end and stride. */
3912 /* Only a single item is referenced given in the start member. */
3914 /* An array ref of the kind (i:), where i is an arbitrary valid index in the
3915 array. The index i is given in the start member. */
3916 CAF_ARR_REF_OPEN_END,
3917 /* An array ref of the kind (:i), where the lower bound of the array ref
3918 is given by the remote side. The index i is given in the end member. */
3919 CAF_ARR_REF_OPEN_START
3924 /* References to remote components of a derived type. */
3925 typedef struct caf_reference_t {
3926 /* A pointer to the next ref or NULL. */
3927 struct caf_reference_t *next;
3928 /* The type of the reference. */
3929 /* caf_ref_type_t, replaced by int to allow specification in fortran FE. */
3931 /* The size of an item referenced in bytes. I.e. in an array ref this is
3932 the factor to advance the array pointer with to get to the next item.
3933 For component refs this gives just the size of the element referenced. */
3937 /* The offset (in bytes) of the component in the derived type.
3938 Unused for allocatable or pointer components. */
3940 /* The offset (in bytes) to the caf_token associated with this
3941 component. NULL, when not allocatable/pointer ref. */
3942 ptrdiff_t caf_token_offset;
3945 /* The mode of the array ref. See CAF_ARR_REF_*. */
3946 /* caf_array_ref_t, replaced by unsigend char to allow specification in
3948 unsigned char mode[GFC_MAX_DIMENSIONS];
3949 /* The type of a static array. Unset for array's with descriptors. */
3950 int static_array_type;
3951 /* Subscript refs (s) or vector refs (v). */
3954 /* The start and end boundary of the ref and the stride. */
3955 index_type start, end, stride;
3958 /* nvec entries of kind giving the elements to reference. */
3960 /* The number of entries in vector. */
3962 /* The integer kind used for the elements in vector. */
3965 } dim[GFC_MAX_DIMENSIONS];
3971 The references make up a single linked list of reference operations. The
3972 @code{NEXT} member links to the next reference or NULL to indicate the end of
3973 the chain. Component and array refs can be arbitrarily mixed as long as they
3974 comply to the Fortran standard.
3977 The member @code{STATIC_ARRAY_TYPE} is used only when the @code{TYPE} is
3978 @code{CAF_REF_STATIC_ARRAY}. The member gives the type of the data referenced.
3979 Because no array descriptor is available for a descriptor-less array and
3980 type conversion still needs to take place the type is transported here.
3982 At the moment @code{CAF_ARR_REF_VECTOR} is not implemented in the front end for
3983 descriptor-less arrays. The library caf_single has untested support for it.
3986 @subsection @code{caf_team_t}
3988 Opaque pointer to represent a team-handle. This type is a stand-in for the
3989 future implementation of teams. It is about to change without further notice.
3991 @node Function ABI Documentation
3992 @section Function ABI Documentation
3995 * _gfortran_caf_init:: Initialiation function
3996 * _gfortran_caf_finish:: Finalization function
3997 * _gfortran_caf_this_image:: Querying the image number
3998 * _gfortran_caf_num_images:: Querying the maximal number of images
3999 * _gfortran_caf_image_status :: Query the status of an image
4000 * _gfortran_caf_failed_images :: Get an array of the indexes of the failed images
4001 * _gfortran_caf_stopped_images :: Get an array of the indexes of the stopped images
4002 * _gfortran_caf_register:: Registering coarrays
4003 * _gfortran_caf_deregister:: Deregistering coarrays
4004 * _gfortran_caf_is_present:: Query whether an allocatable or pointer component in a derived type coarray is allocated
4005 * _gfortran_caf_send:: Sending data from a local image to a remote image
4006 * _gfortran_caf_get:: Getting data from a remote image
4007 * _gfortran_caf_sendget:: Sending data between remote images
4008 * _gfortran_caf_send_by_ref:: Sending data from a local image to a remote image using enhanced references
4009 * _gfortran_caf_get_by_ref:: Getting data from a remote image using enhanced references
4010 * _gfortran_caf_sendget_by_ref:: Sending data between remote images using enhanced references
4011 * _gfortran_caf_lock:: Locking a lock variable
4012 * _gfortran_caf_unlock:: Unlocking a lock variable
4013 * _gfortran_caf_event_post:: Post an event
4014 * _gfortran_caf_event_wait:: Wait that an event occurred
4015 * _gfortran_caf_event_query:: Query event count
4016 * _gfortran_caf_sync_all:: All-image barrier
4017 * _gfortran_caf_sync_images:: Barrier for selected images
4018 * _gfortran_caf_sync_memory:: Wait for completion of segment-memory operations
4019 * _gfortran_caf_error_stop:: Error termination with exit code
4020 * _gfortran_caf_error_stop_str:: Error termination with string
4021 * _gfortran_caf_fail_image :: Mark the image failed and end its execution
4022 * _gfortran_caf_atomic_define:: Atomic variable assignment
4023 * _gfortran_caf_atomic_ref:: Atomic variable reference
4024 * _gfortran_caf_atomic_cas:: Atomic compare and swap
4025 * _gfortran_caf_atomic_op:: Atomic operation
4026 * _gfortran_caf_co_broadcast:: Sending data to all images
4027 * _gfortran_caf_co_max:: Collective maximum reduction
4028 * _gfortran_caf_co_min:: Collective minimum reduction
4029 * _gfortran_caf_co_sum:: Collective summing reduction
4030 * _gfortran_caf_co_reduce:: Generic collective reduction
4034 @node _gfortran_caf_init
4035 @subsection @code{_gfortran_caf_init} --- Initialiation function
4036 @cindex Coarray, _gfortran_caf_init
4039 @item @emph{Description}:
4040 This function is called at startup of the program before the Fortran main
4041 program, if the latter has been compiled with @option{-fcoarray=lib}.
4042 It takes as arguments the command-line arguments of the program. It is
4043 permitted to pass two @code{NULL} pointers as argument; if non-@code{NULL},
4044 the library is permitted to modify the arguments.
4046 @item @emph{Syntax}:
4047 @code{void _gfortran_caf_init (int *argc, char ***argv)}
4049 @item @emph{Arguments}:
4050 @multitable @columnfractions .15 .70
4051 @item @var{argc} @tab intent(inout) An integer pointer with the number of
4052 arguments passed to the program or @code{NULL}.
4053 @item @var{argv} @tab intent(inout) A pointer to an array of strings with the
4054 command-line arguments or @code{NULL}.
4058 The function is modelled after the initialization function of the Message
4059 Passing Interface (MPI) specification. Due to the way coarray registration
4060 works, it might not be the first call to the library. If the main program is
4061 not written in Fortran and only a library uses coarrays, it can happen that
4062 this function is never called. Therefore, it is recommended that the library
4063 does not rely on the passed arguments and whether the call has been done.
4067 @node _gfortran_caf_finish
4068 @subsection @code{_gfortran_caf_finish} --- Finalization function
4069 @cindex Coarray, _gfortran_caf_finish
4072 @item @emph{Description}:
4073 This function is called at the end of the Fortran main program, if it has
4074 been compiled with the @option{-fcoarray=lib} option.
4076 @item @emph{Syntax}:
4077 @code{void _gfortran_caf_finish (void)}
4080 For non-Fortran programs, it is recommended to call the function at the end
4081 of the main program. To ensure that the shutdown is also performed for
4082 programs where this function is not explicitly invoked, for instance
4083 non-Fortran programs or calls to the system's exit() function, the library
4084 can use a destructor function. Note that programs can also be terminated
4085 using the STOP and ERROR STOP statements; those use different library calls.
4089 @node _gfortran_caf_this_image
4090 @subsection @code{_gfortran_caf_this_image} --- Querying the image number
4091 @cindex Coarray, _gfortran_caf_this_image
4094 @item @emph{Description}:
4095 This function returns the current image number, which is a positive number.
4097 @item @emph{Syntax}:
4098 @code{int _gfortran_caf_this_image (int distance)}
4100 @item @emph{Arguments}:
4101 @multitable @columnfractions .15 .70
4102 @item @var{distance} @tab As specified for the @code{this_image} intrinsic
4103 in TS18508. Shall be a non-negative number.
4107 If the Fortran intrinsic @code{this_image} is invoked without an argument, which
4108 is the only permitted form in Fortran 2008, GCC passes @code{0} as
4113 @node _gfortran_caf_num_images
4114 @subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images
4115 @cindex Coarray, _gfortran_caf_num_images
4118 @item @emph{Description}:
4119 This function returns the number of images in the current team, if
4120 @var{distance} is 0 or the number of images in the parent team at the specified
4121 distance. If failed is -1, the function returns the number of all images at
4122 the specified distance; if it is 0, the function returns the number of
4123 nonfailed images, and if it is 1, it returns the number of failed images.
4125 @item @emph{Syntax}:
4126 @code{int _gfortran_caf_num_images(int distance, int failed)}
4128 @item @emph{Arguments}:
4129 @multitable @columnfractions .15 .70
4130 @item @var{distance} @tab the distance from this image to the ancestor.
4132 @item @var{failed} @tab shall be -1, 0, or 1
4136 This function follows TS18508. If the num_image intrinsic has no arguments,
4137 then the compiler passes @code{distance=0} and @code{failed=-1} to the function.
4141 @node _gfortran_caf_image_status
4142 @subsection @code{_gfortran_caf_image_status} --- Query the status of an image
4143 @cindex Coarray, _gfortran_caf_image_status
4146 @item @emph{Description}:
4147 Get the status of the image given by the id @var{image} of the team given by
4148 @var{team}. Valid results are zero, for image is ok, @code{STAT_STOPPED_IMAGE}
4149 from the ISO_FORTRAN_ENV module to indicate that the image has been stopped and
4150 @code{STAT_FAILED_IMAGE} also from ISO_FORTRAN_ENV to indicate that the image
4151 has executed a @code{FAIL IMAGE} statement.
4153 @item @emph{Syntax}:
4154 @code{int _gfortran_caf_image_status (int image, caf_team_t * team)}
4156 @item @emph{Arguments}:
4157 @multitable @columnfractions .15 .70
4158 @item @var{image} @tab the positive scalar id of the image in the current TEAM.
4159 @item @var{team} @tab optional; team on the which the inquiry is to be
4164 This function follows TS18508. Because team-functionality is not yet
4165 implemented a null-pointer is passed for the @var{team} argument at the moment.
4169 @node _gfortran_caf_failed_images
4170 @subsection @code{_gfortran_caf_failed_images} --- Get an array of the indexes of the failed images
4171 @cindex Coarray, _gfortran_caf_failed_images
4174 @item @emph{Description}:
4175 Get an array of image indexes in the current @var{team} that have failed. The
4176 array is sorted ascendingly. When @var{team} is not provided the current team
4177 is to be used. When @var{kind} is provided then the resulting array is of that
4178 integer kind else it is of default integer kind. The returns an unallocated
4179 size zero array when no images have failed.
4181 @item @emph{Syntax}:
4182 @code{int _gfortran_caf_failed_images (caf_team_t * team, int * kind)}
4184 @item @emph{Arguments}:
4185 @multitable @columnfractions .15 .70
4186 @item @var{team} @tab optional; team on the which the inquiry is to be
4188 @item @var{image} @tab optional; the kind of the resulting integer array.
4192 This function follows TS18508. Because team-functionality is not yet
4193 implemented a null-pointer is passed for the @var{team} argument at the moment.
4197 @node _gfortran_caf_stopped_images
4198 @subsection @code{_gfortran_caf_stopped_images} --- Get an array of the indexes of the stopped images
4199 @cindex Coarray, _gfortran_caf_stopped_images
4202 @item @emph{Description}:
4203 Get an array of image indexes in the current @var{team} that have stopped. The
4204 array is sorted ascendingly. When @var{team} is not provided the current team
4205 is to be used. When @var{kind} is provided then the resulting array is of that
4206 integer kind else it is of default integer kind. The returns an unallocated
4207 size zero array when no images have failed.
4209 @item @emph{Syntax}:
4210 @code{int _gfortran_caf_stopped_images (caf_team_t * team, int * kind)}
4212 @item @emph{Arguments}:
4213 @multitable @columnfractions .15 .70
4214 @item @var{team} @tab optional; team on the which the inquiry is to be
4216 @item @var{image} @tab optional; the kind of the resulting integer array.
4220 This function follows TS18508. Because team-functionality is not yet
4221 implemented a null-pointer is passed for the @var{team} argument at the moment.
4225 @node _gfortran_caf_register
4226 @subsection @code{_gfortran_caf_register} --- Registering coarrays
4227 @cindex Coarray, _gfortran_caf_register
4230 @item @emph{Description}:
4231 Registers memory for a coarray and creates a token to identify the coarray. The
4232 routine is called for both coarrays with @code{SAVE} attribute and using an
4233 explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a
4234 @code{NULL} pointer, the function shall abort with printing an error message
4235 and starting the error termination. If no error occurs and @var{STAT} is
4236 present, it shall be set to zero. Otherwise, it shall be set to a positive
4237 value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing
4238 the failure. The routine shall register the memory provided in the
4239 @code{DATA}-component of the array descriptor @var{DESC}, when that component
4240 is non-@code{NULL}, else it shall allocate sufficient memory and provide a
4241 pointer to it in the @code{DATA}-component of @var{DESC}. The array descriptor
4242 has rank zero, when a scalar object is to be registered and the array
4243 descriptor may be invalid after the call to @code{_gfortran_caf_register}.
4244 When an array is to be allocated the descriptor persists.
4246 For @code{CAF_REGTYPE_COARRAY_STATIC} and @code{CAF_REGTYPE_COARRAY_ALLOC},
4247 the passed size is the byte size requested. For @code{CAF_REGTYPE_LOCK_STATIC},
4248 @code{CAF_REGTYPE_LOCK_ALLOC} and @code{CAF_REGTYPE_CRITICAL} it is the array
4249 size or one for a scalar.
4251 When @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} is used, then only a token
4252 for an allocatable or pointer component is created. The @code{SIZE} parameter
4253 is not used then. On the contrary when
4254 @code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} is specified, then the
4255 @var{token} needs to be registered by a previous call with regtype
4256 @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and either the memory specified
4257 in the @var{DESC}'s data-ptr is registered or allocate when the data-ptr is
4260 @item @emph{Syntax}:
4261 @code{void caf_register (size_t size, caf_register_t type, caf_token_t *token,
4262 gfc_descriptor_t *desc, int *stat, char *errmsg, size_t errmsg_len)}
4264 @item @emph{Arguments}:
4265 @multitable @columnfractions .15 .70
4266 @item @var{size} @tab For normal coarrays, the byte size of the coarray to be
4267 allocated; for lock types and event types, the number of elements.
4268 @item @var{type} @tab one of the caf_register_t types.
4269 @item @var{token} @tab intent(out) An opaque pointer identifying the coarray.
4270 @item @var{desc} @tab intent(inout) The (pseudo) array descriptor.
4271 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
4273 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4274 an error message; may be @code{NULL}
4275 @item @var{errmsg_len} @tab the buffer size of errmsg.
4279 Nonallocatable coarrays have to be registered prior use from remote images.
4280 In order to guarantee this, they have to be registered before the main
4281 program. This can be achieved by creating constructor functions. That is what
4282 GCC does such that also for nonallocatable coarrays the memory is allocated and
4283 no static memory is used. The token permits to identify the coarray; to the
4284 processor, the token is a nonaliasing pointer. The library can, for instance,
4285 store the base address of the coarray in the token, some handle or a more
4286 complicated struct. The library may also store the array descriptor
4287 @var{DESC} when its rank is non-zero.
4289 For lock types, the value shall only be used for checking the allocation
4290 status. Note that for critical blocks, the locking is only required on one
4291 image; in the locking statement, the processor shall always pass an
4292 image index of one for critical-block lock variables
4293 (@code{CAF_REGTYPE_CRITICAL}). For lock types and critical-block variables,
4294 the initial value shall be unlocked (or, respectively, not in critical
4295 section) such as the value false; for event types, the initial state should
4296 be no event, e.g. zero.
4300 @node _gfortran_caf_deregister
4301 @subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays
4302 @cindex Coarray, _gfortran_caf_deregister
4305 @item @emph{Description}:
4306 Called to free or deregister the memory of a coarray; the processor calls this
4307 function for automatic and explicit deallocation. In case of an error, this
4308 function shall fail with an error message, unless the @var{STAT} variable is
4309 not null. The library is only expected to free memory it allocated itself
4310 during a call to @code{_gfortran_caf_register}.
4312 @item @emph{Syntax}:
4313 @code{void caf_deregister (caf_token_t *token, caf_deregister_t type,
4314 int *stat, char *errmsg, size_t errmsg_len)}
4316 @item @emph{Arguments}:
4317 @multitable @columnfractions .15 .70
4318 @item @var{token} @tab the token to free.
4319 @item @var{type} @tab the type of action to take for the coarray. A
4320 @code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} is allowed only for allocatable or
4321 pointer components of derived type coarrays. The action only deallocates the
4322 local memory without deleting the token.
4323 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
4324 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set
4325 to an error message; may be NULL
4326 @item @var{errmsg_len} @tab the buffer size of errmsg.
4330 For nonalloatable coarrays this function is never called. If a cleanup is
4331 required, it has to be handled via the finish, stop and error stop functions,
4332 and via destructors.
4336 @node _gfortran_caf_is_present
4337 @subsection @code{_gfortran_caf_is_present} --- Query whether an allocatable or pointer component in a derived type coarray is allocated
4338 @cindex Coarray, _gfortran_caf_is_present
4341 @item @emph{Description}:
4342 Used to query the coarray library whether an allocatable component in a derived
4343 type coarray is allocated on a remote image.
4345 @item @emph{Syntax}:
4346 @code{void _gfortran_caf_is_present (caf_token_t token, int image_index,
4347 gfc_reference_t *ref)}
4349 @item @emph{Arguments}:
4350 @multitable @columnfractions .15 .70
4351 @item @var{token} @tab An opaque pointer identifying the coarray.
4352 @item @var{image_index} @tab The ID of the remote image; must be a positive
4354 @item @var{ref} @tab A chain of references to address the allocatable or
4355 pointer component in the derived type coarray. The object reference needs to be
4356 a scalar or a full array reference, respectively.
4361 @node _gfortran_caf_send
4362 @subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image
4363 @cindex Coarray, _gfortran_caf_send
4366 @item @emph{Description}:
4367 Called to send a scalar, an array section or a whole array from a local
4368 to a remote image identified by the image_index.
4370 @item @emph{Syntax}:
4371 @code{void _gfortran_caf_send (caf_token_t token, size_t offset,
4372 int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
4373 gfc_descriptor_t *src, int dst_kind, int src_kind, bool may_require_tmp,
4376 @item @emph{Arguments}:
4377 @multitable @columnfractions .15 .70
4378 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4379 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
4380 shifted compared to the base address of the coarray.
4381 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4383 @item @var{dest} @tab intent(in) Array descriptor for the remote image for the
4384 bounds and the size. The @code{base_addr} shall not be accessed.
4385 @item @var{dst_vector} @tab intent(in) If not NULL, it contains the vector
4386 subscript of the destination array; the values are relative to the dimension
4387 triplet of the dest argument.
4388 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4389 transferred to the remote image
4390 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4391 @item @var{src_kind} @tab intent(in) Kind of the source argument
4392 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4393 it is known at compile time that the @var{dest} and @var{src} either cannot
4394 overlap or overlap (fully or partially) such that walking @var{src} and
4395 @var{dest} in element wise element order (honoring the stride value) will not
4396 lead to wrong results. Otherwise, the value is @code{true}.
4397 @item @var{stat} @tab intent(out) when non-NULL give the result of the
4398 operation, i.e., zero on success and non-zero on error. When NULL and an error
4399 occurs, then an error message is printed and the program is terminated.
4403 It is permitted to have @var{image_index} equal the current image; the memory
4404 of the send-to and the send-from might (partially) overlap in that case. The
4405 implementation has to take care that it handles this case, e.g. using
4406 @code{memmove} which handles (partially) overlapping memory. If
4407 @var{may_require_tmp} is true, the library might additionally create a
4408 temporary variable, unless additional checks show that this is not required
4409 (e.g. because walking backward is possible or because both arrays are
4410 contiguous and @code{memmove} takes care of overlap issues).
4412 Note that the assignment of a scalar to an array is permitted. In addition,
4413 the library has to handle numeric-type conversion and for strings, padding
4414 and different character kinds.
4418 @node _gfortran_caf_get
4419 @subsection @code{_gfortran_caf_get} --- Getting data from a remote image
4420 @cindex Coarray, _gfortran_caf_get
4423 @item @emph{Description}:
4424 Called to get an array section or a whole array from a remote,
4425 image identified by the image_index.
4427 @item @emph{Syntax}:
4428 @code{void _gfortran_caf_get (caf_token_t token, size_t offset,
4429 int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector,
4430 gfc_descriptor_t *dest, int src_kind, int dst_kind, bool may_require_tmp,
4433 @item @emph{Arguments}:
4434 @multitable @columnfractions .15 .70
4435 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4436 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
4437 shifted compared to the base address of the coarray.
4438 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4440 @item @var{dest} @tab intent(out) Array descriptor of the local array to store
4441 the data retrieved from the remote image
4442 @item @var{src} @tab intent(in) Array descriptor for the remote image for the
4443 bounds and the size. The @code{base_addr} shall not be accessed.
4444 @item @var{src_vector} @tab intent(in) If not NULL, it contains the vector
4445 subscript of the source array; the values are relative to the dimension
4446 triplet of the @var{src} argument.
4447 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4448 @item @var{src_kind} @tab intent(in) Kind of the source argument
4449 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4450 it is known at compile time that the @var{dest} and @var{src} either cannot
4451 overlap or overlap (fully or partially) such that walking @var{src} and
4452 @var{dest} in element wise element order (honoring the stride value) will not
4453 lead to wrong results. Otherwise, the value is @code{true}.
4454 @item @var{stat} @tab intent(out) When non-NULL give the result of the
4455 operation, i.e., zero on success and non-zero on error. When NULL and an error
4456 occurs, then an error message is printed and the program is terminated.
4460 It is permitted to have @var{image_index} equal the current image; the memory of
4461 the send-to and the send-from might (partially) overlap in that case. The
4462 implementation has to take care that it handles this case, e.g. using
4463 @code{memmove} which handles (partially) overlapping memory. If
4464 @var{may_require_tmp} is true, the library might additionally create a
4465 temporary variable, unless additional checks show that this is not required
4466 (e.g. because walking backward is possible or because both arrays are
4467 contiguous and @code{memmove} takes care of overlap issues).
4469 Note that the library has to handle numeric-type conversion and for strings,
4470 padding and different character kinds.
4474 @node _gfortran_caf_sendget
4475 @subsection @code{_gfortran_caf_sendget} --- Sending data between remote images
4476 @cindex Coarray, _gfortran_caf_sendget
4479 @item @emph{Description}:
4480 Called to send a scalar, an array section or a whole array from a remote image
4481 identified by the @var{src_image_index} to a remote image identified by the
4482 @var{dst_image_index}.
4484 @item @emph{Syntax}:
4485 @code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset,
4486 int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
4487 caf_token_t src_token, size_t src_offset, int src_image_index,
4488 gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind,
4489 bool may_require_tmp, int *stat)}
4491 @item @emph{Arguments}:
4492 @multitable @columnfractions .15 .70
4493 @item @var{dst_token} @tab intent(in) An opaque pointer identifying the
4494 destination coarray.
4495 @item @var{dst_offset} @tab intent(in) By which amount of bytes the actual data
4496 is shifted compared to the base address of the destination coarray.
4497 @item @var{dst_image_index} @tab intent(in) The ID of the destination remote
4498 image; must be a positive number.
4499 @item @var{dest} @tab intent(in) Array descriptor for the destination
4500 remote image for the bounds and the size. The @code{base_addr} shall not be
4502 @item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
4503 subscript of the destination array; the values are relative to the dimension
4504 triplet of the @var{dest} argument.
4505 @item @var{src_token} @tab intent(in) An opaque pointer identifying the source
4507 @item @var{src_offset} @tab intent(in) By which amount of bytes the actual data
4508 is shifted compared to the base address of the source coarray.
4509 @item @var{src_image_index} @tab intent(in) The ID of the source remote image;
4510 must be a positive number.
4511 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4512 transferred to the remote image.
4513 @item @var{src_vector} @tab intent(in) Array descriptor of the local array to
4514 be transferred to the remote image
4515 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4516 @item @var{src_kind} @tab intent(in) Kind of the source argument
4517 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4518 it is known at compile time that the @var{dest} and @var{src} either cannot
4519 overlap or overlap (fully or partially) such that walking @var{src} and
4520 @var{dest} in element wise element order (honoring the stride value) will not
4521 lead to wrong results. Otherwise, the value is @code{true}.
4522 @item @var{stat} @tab intent(out) when non-NULL give the result of the
4523 operation, i.e., zero on success and non-zero on error. When NULL and an error
4524 occurs, then an error message is printed and the program is terminated.
4528 It is permitted to have the same image index for both @var{src_image_index} and
4529 @var{dst_image_index}; the memory of the send-to and the send-from might
4530 (partially) overlap in that case. The implementation has to take care that it
4531 handles this case, e.g. using @code{memmove} which handles (partially)
4532 overlapping memory. If @var{may_require_tmp} is true, the library
4533 might additionally create a temporary variable, unless additional checks show
4534 that this is not required (e.g. because walking backward is possible or because
4535 both arrays are contiguous and @code{memmove} takes care of overlap issues).
4537 Note that the assignment of a scalar to an array is permitted. In addition,
4538 the library has to handle numeric-type conversion and for strings, padding and
4539 different character kinds.
4542 @node _gfortran_caf_send_by_ref
4543 @subsection @code{_gfortran_caf_send_by_ref} --- Sending data from a local image to a remote image with enhanced referencing options
4544 @cindex Coarray, _gfortran_caf_send_by_ref
4547 @item @emph{Description}:
4548 Called to send a scalar, an array section or a whole array from a local to a
4549 remote image identified by the @var{image_index}.
4551 @item @emph{Syntax}:
4552 @code{void _gfortran_caf_send_by_ref (caf_token_t token, int image_index,
4553 gfc_descriptor_t *src, caf_reference_t *refs, int dst_kind, int src_kind,
4554 bool may_require_tmp, bool dst_reallocatable, int *stat, int dst_type)}
4556 @item @emph{Arguments}:
4557 @multitable @columnfractions .15 .70
4558 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4559 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4561 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4562 transferred to the remote image
4563 @item @var{refs} @tab intent(in) The references on the remote array to store
4564 the data given by src. Guaranteed to have at least one entry.
4565 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4566 @item @var{src_kind} @tab intent(in) Kind of the source argument
4567 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4568 it is known at compile time that the @var{dest} and @var{src} either cannot
4569 overlap or overlap (fully or partially) such that walking @var{src} and
4570 @var{dest} in element wise element order (honoring the stride value) will not
4571 lead to wrong results. Otherwise, the value is @code{true}.
4572 @item @var{dst_reallocatable} @tab intent(in) Set when the destination is of
4573 allocatable or pointer type and the refs will allow reallocation, i.e., the ref
4574 is a full array or component ref.
4575 @item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the
4576 operation, i.e., zero on success and non-zero on error. When @code{NULL} and
4577 an error occurs, then an error message is printed and the program is terminated.
4578 @item @var{dst_type} @tab intent(in) Give the type of the destination. When
4579 the destination is not an array, than the precise type, e.g. of a component in
4580 a derived type, is not known, but provided here.
4584 It is permitted to have @var{image_index} equal the current image; the memory of
4585 the send-to and the send-from might (partially) overlap in that case. The
4586 implementation has to take care that it handles this case, e.g. using
4587 @code{memmove} which handles (partially) overlapping memory. If
4588 @var{may_require_tmp} is true, the library might additionally create a
4589 temporary variable, unless additional checks show that this is not required
4590 (e.g. because walking backward is possible or because both arrays are
4591 contiguous and @code{memmove} takes care of overlap issues).
4593 Note that the assignment of a scalar to an array is permitted. In addition,
4594 the library has to handle numeric-type conversion and for strings, padding
4595 and different character kinds.
4597 Because of the more complicated references possible some operations may be
4598 unsupported by certain libraries. The library is expected to issue a precise
4599 error message why the operation is not permitted.
4603 @node _gfortran_caf_get_by_ref
4604 @subsection @code{_gfortran_caf_get_by_ref} --- Getting data from a remote image using enhanced references
4605 @cindex Coarray, _gfortran_caf_get_by_ref
4608 @item @emph{Description}:
4609 Called to get a scalar, an array section or a whole array from a remote image
4610 identified by the @var{image_index}.
4612 @item @emph{Syntax}:
4613 @code{void _gfortran_caf_get_by_ref (caf_token_t token, int image_index,
4614 caf_reference_t *refs, gfc_descriptor_t *dst, int dst_kind, int src_kind,
4615 bool may_require_tmp, bool dst_reallocatable, int *stat, int src_type)}
4617 @item @emph{Arguments}:
4618 @multitable @columnfractions .15 .70
4619 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4620 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4622 @item @var{refs} @tab intent(in) The references to apply to the remote structure
4624 @item @var{dst} @tab intent(in) Array descriptor of the local array to store
4625 the data transferred from the remote image. May be reallocated where needed
4626 and when @var{DST_REALLOCATABLE} allows it.
4627 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4628 @item @var{src_kind} @tab intent(in) Kind of the source argument
4629 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4630 it is known at compile time that the @var{dest} and @var{src} either cannot
4631 overlap or overlap (fully or partially) such that walking @var{src} and
4632 @var{dest} in element wise element order (honoring the stride value) will not
4633 lead to wrong results. Otherwise, the value is @code{true}.
4634 @item @var{dst_reallocatable} @tab intent(in) Set when @var{DST} is of
4635 allocatable or pointer type and its refs allow reallocation, i.e., the full
4636 array or a component is referenced.
4637 @item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the
4638 operation, i.e., zero on success and non-zero on error. When @code{NULL} and an
4639 error occurs, then an error message is printed and the program is terminated.
4640 @item @var{src_type} @tab intent(in) Give the type of the source. When the
4641 source is not an array, than the precise type, e.g. of a component in a
4642 derived type, is not known, but provided here.
4646 It is permitted to have @code{image_index} equal the current image; the memory
4647 of the send-to and the send-from might (partially) overlap in that case. The
4648 implementation has to take care that it handles this case, e.g. using
4649 @code{memmove} which handles (partially) overlapping memory. If
4650 @var{may_require_tmp} is true, the library might additionally create a
4651 temporary variable, unless additional checks show that this is not required
4652 (e.g. because walking backward is possible or because both arrays are
4653 contiguous and @code{memmove} takes care of overlap issues).
4655 Note that the library has to handle numeric-type conversion and for strings,
4656 padding and different character kinds.
4658 Because of the more complicated references possible some operations may be
4659 unsupported by certain libraries. The library is expected to issue a precise
4660 error message why the operation is not permitted.
4664 @node _gfortran_caf_sendget_by_ref
4665 @subsection @code{_gfortran_caf_sendget_by_ref} --- Sending data between remote images using enhanced references on both sides
4666 @cindex Coarray, _gfortran_caf_sendget_by_ref
4669 @item @emph{Description}:
4670 Called to send a scalar, an array section or a whole array from a remote image
4671 identified by the @var{src_image_index} to a remote image identified by the
4672 @var{dst_image_index}.
4674 @item @emph{Syntax}:
4675 @code{void _gfortran_caf_sendget_by_ref (caf_token_t dst_token,
4676 int dst_image_index, caf_reference_t *dst_refs,
4677 caf_token_t src_token, int src_image_index, caf_reference_t *src_refs,
4678 int dst_kind, int src_kind, bool may_require_tmp, int *dst_stat,
4679 int *src_stat, int dst_type, int src_type)}
4681 @item @emph{Arguments}:
4682 @multitable @columnfractions .15 .70
4683 @item @var{dst_token} @tab intent(in) An opaque pointer identifying the
4684 destination coarray.
4685 @item @var{dst_image_index} @tab intent(in) The ID of the destination remote
4686 image; must be a positive number.
4687 @item @var{dst_refs} @tab intent(in) The references on the remote array to store
4688 the data given by the source. Guaranteed to have at least one entry.
4689 @item @var{src_token} @tab intent(in) An opaque pointer identifying the source
4691 @item @var{src_image_index} @tab intent(in) The ID of the source remote image;
4692 must be a positive number.
4693 @item @var{src_refs} @tab intent(in) The references to apply to the remote
4694 structure to get the data.
4695 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4696 @item @var{src_kind} @tab intent(in) Kind of the source argument
4697 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4698 it is known at compile time that the @var{dest} and @var{src} either cannot
4699 overlap or overlap (fully or partially) such that walking @var{src} and
4700 @var{dest} in element wise element order (honoring the stride value) will not
4701 lead to wrong results. Otherwise, the value is @code{true}.
4702 @item @var{dst_stat} @tab intent(out) when non-@code{NULL} give the result of
4703 the send-operation, i.e., zero on success and non-zero on error. When
4704 @code{NULL} and an error occurs, then an error message is printed and the
4705 program is terminated.
4706 @item @var{src_stat} @tab intent(out) When non-@code{NULL} give the result of
4707 the get-operation, i.e., zero on success and non-zero on error. When
4708 @code{NULL} and an error occurs, then an error message is printed and the
4709 program is terminated.
4710 @item @var{dst_type} @tab intent(in) Give the type of the destination. When
4711 the destination is not an array, than the precise type, e.g. of a component in
4712 a derived type, is not known, but provided here.
4713 @item @var{src_type} @tab intent(in) Give the type of the source. When the
4714 source is not an array, than the precise type, e.g. of a component in a
4715 derived type, is not known, but provided here.
4719 It is permitted to have the same image index for both @var{src_image_index} and
4720 @var{dst_image_index}; the memory of the send-to and the send-from might
4721 (partially) overlap in that case. The implementation has to take care that it
4722 handles this case, e.g. using @code{memmove} which handles (partially)
4723 overlapping memory. If @var{may_require_tmp} is true, the library
4724 might additionally create a temporary variable, unless additional checks show
4725 that this is not required (e.g. because walking backward is possible or because
4726 both arrays are contiguous and @code{memmove} takes care of overlap issues).
4728 Note that the assignment of a scalar to an array is permitted. In addition,
4729 the library has to handle numeric-type conversion and for strings, padding and
4730 different character kinds.
4732 Because of the more complicated references possible some operations may be
4733 unsupported by certain libraries. The library is expected to issue a precise
4734 error message why the operation is not permitted.
4738 @node _gfortran_caf_lock
4739 @subsection @code{_gfortran_caf_lock} --- Locking a lock variable
4740 @cindex Coarray, _gfortran_caf_lock
4743 @item @emph{Description}:
4744 Acquire a lock on the given image on a scalar locking variable or for the
4745 given array element for an array-valued variable. If the @var{acquired_lock}
4746 is @code{NULL}, the function returns after having obtained the lock. If it is
4747 non-@code{NULL}, then @var{acquired_lock} is assigned the value true (one) when
4748 the lock could be obtained and false (zero) otherwise. Locking a lock variable
4749 which has already been locked by the same image is an error.
4751 @item @emph{Syntax}:
4752 @code{void _gfortran_caf_lock (caf_token_t token, size_t index, int image_index,
4753 int *acquired_lock, int *stat, char *errmsg, size_t errmsg_len)}
4755 @item @emph{Arguments}:
4756 @multitable @columnfractions .15 .70
4757 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4758 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4759 scalars, it is always 0.
4760 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4762 @item @var{acquired_lock} @tab intent(out) If not NULL, it returns whether lock
4764 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
4765 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4766 an error message; may be NULL.
4767 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4771 This function is also called for critical blocks; for those, the array index
4772 is always zero and the image index is one. Libraries are permitted to use other
4773 images for critical-block locking variables.
4776 @node _gfortran_caf_unlock
4777 @subsection @code{_gfortran_caf_lock} --- Unlocking a lock variable
4778 @cindex Coarray, _gfortran_caf_unlock
4781 @item @emph{Description}:
4782 Release a lock on the given image on a scalar locking variable or for the
4783 given array element for an array-valued variable. Unlocking a lock variable
4784 which is unlocked or has been locked by a different image is an error.
4786 @item @emph{Syntax}:
4787 @code{void _gfortran_caf_unlock (caf_token_t token, size_t index, int image_index,
4788 int *stat, char *errmsg, size_t errmsg_len)}
4790 @item @emph{Arguments}:
4791 @multitable @columnfractions .15 .70
4792 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4793 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4794 scalars, it is always 0.
4795 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4797 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
4799 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4800 an error message; may be NULL.
4801 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4805 This function is also called for critical block; for those, the array index
4806 is always zero and the image index is one. Libraries are permitted to use other
4807 images for critical-block locking variables.
4810 @node _gfortran_caf_event_post
4811 @subsection @code{_gfortran_caf_event_post} --- Post an event
4812 @cindex Coarray, _gfortran_caf_event_post
4815 @item @emph{Description}:
4816 Increment the event count of the specified event variable.
4818 @item @emph{Syntax}:
4819 @code{void _gfortran_caf_event_post (caf_token_t token, size_t index,
4820 int image_index, int *stat, char *errmsg, size_t errmsg_len)}
4822 @item @emph{Arguments}:
4823 @multitable @columnfractions .15 .70
4824 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4825 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4826 scalars, it is always 0.
4827 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4828 positive number; zero indicates the current image, when accessed noncoindexed.
4829 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
4830 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4831 an error message; may be NULL.
4832 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4836 This acts like an atomic add of one to the remote image's event variable.
4837 The statement is an image-control statement but does not imply sync memory.
4838 Still, all preceding push communications of this image to the specified
4839 remote image have to be completed before @code{event_wait} on the remote
4845 @node _gfortran_caf_event_wait
4846 @subsection @code{_gfortran_caf_event_wait} --- Wait that an event occurred
4847 @cindex Coarray, _gfortran_caf_event_wait
4850 @item @emph{Description}:
4851 Wait until the event count has reached at least the specified
4852 @var{until_count}; if so, atomically decrement the event variable by this
4855 @item @emph{Syntax}:
4856 @code{void _gfortran_caf_event_wait (caf_token_t token, size_t index,
4857 int until_count, int *stat, char *errmsg, size_t errmsg_len)}
4859 @item @emph{Arguments}:
4860 @multitable @columnfractions .15 .70
4861 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4862 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4863 scalars, it is always 0.
4864 @item @var{until_count} @tab intent(in) The number of events which have to be
4865 available before the function returns.
4866 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
4867 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4868 an error message; may be NULL.
4869 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4873 This function only operates on a local coarray. It acts like a loop checking
4874 atomically the value of the event variable, breaking if the value is greater
4875 or equal the requested number of counts. Before the function returns, the
4876 event variable has to be decremented by the requested @var{until_count} value.
4877 A possible implementation would be a busy loop for a certain number of spins
4878 (possibly depending on the number of threads relative to the number of available
4879 cores) followed by another waiting strategy such as a sleeping wait (possibly
4880 with an increasing number of sleep time) or, if possible, a futex wait.
4882 The statement is an image-control statement but does not imply sync memory.
4883 Still, all preceding push communications of this image to the specified
4884 remote image have to be completed before @code{event_wait} on the remote
4890 @node _gfortran_caf_event_query
4891 @subsection @code{_gfortran_caf_event_query} --- Query event count
4892 @cindex Coarray, _gfortran_caf_event_query
4895 @item @emph{Description}:
4896 Return the event count of the specified event variable.
4898 @item @emph{Syntax}:
4899 @code{void _gfortran_caf_event_query (caf_token_t token, size_t index,
4900 int image_index, int *count, int *stat)}
4902 @item @emph{Arguments}:
4903 @multitable @columnfractions .15 .70
4904 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4905 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4906 scalars, it is always 0.
4907 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4908 positive number; zero indicates the current image when accessed noncoindexed.
4909 @item @var{count} @tab intent(out) The number of events currently posted to
4911 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
4915 The typical use is to check the local event variable to only call
4916 @code{event_wait} when the data is available. However, a coindexed variable
4917 is permitted; there is no ordering or synchronization implied. It acts like
4918 an atomic fetch of the value of the event variable.
4923 @node _gfortran_caf_sync_all
4924 @subsection @code{_gfortran_caf_sync_all} --- All-image barrier
4925 @cindex Coarray, _gfortran_caf_sync_all
4928 @item @emph{Description}:
4929 Synchronization of all images in the current team; the program only continues
4930 on a given image after this function has been called on all images of the
4931 current team. Additionally, it ensures that all pending data transfers of
4932 previous segment have completed.
4934 @item @emph{Syntax}:
4935 @code{void _gfortran_caf_sync_all (int *stat, char *errmsg, size_t errmsg_len)}
4937 @item @emph{Arguments}:
4938 @multitable @columnfractions .15 .70
4939 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4940 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4941 an error message; may be NULL.
4942 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4948 @node _gfortran_caf_sync_images
4949 @subsection @code{_gfortran_caf_sync_images} --- Barrier for selected images
4950 @cindex Coarray, _gfortran_caf_sync_images
4953 @item @emph{Description}:
4954 Synchronization between the specified images; the program only continues on a
4955 given image after this function has been called on all images specified for
4956 that image. Note that one image can wait for all other images in the current
4957 team (e.g. via @code{sync images(*)}) while those only wait for that specific
4958 image. Additionally, @code{sync images} ensures that all pending data
4959 transfers of previous segments have completed.
4961 @item @emph{Syntax}:
4962 @code{void _gfortran_caf_sync_images (int count, int images[], int *stat,
4963 char *errmsg, size_t errmsg_len)}
4965 @item @emph{Arguments}:
4966 @multitable @columnfractions .15 .70
4967 @item @var{count} @tab intent(in) The number of images which are provided in
4968 the next argument. For a zero-sized array, the value is zero. For
4969 @code{sync images (*)}, the value is @math{-1}.
4970 @item @var{images} @tab intent(in) An array with the images provided by the
4971 user. If @var{count} is zero, a NULL pointer is passed.
4972 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4973 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4974 an error message; may be NULL.
4975 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4981 @node _gfortran_caf_sync_memory
4982 @subsection @code{_gfortran_caf_sync_memory} --- Wait for completion of segment-memory operations
4983 @cindex Coarray, _gfortran_caf_sync_memory
4986 @item @emph{Description}:
4987 Acts as optimization barrier between different segments. It also ensures that
4988 all pending memory operations of this image have been completed.
4990 @item @emph{Syntax}:
4991 @code{void _gfortran_caf_sync_memory (int *stat, char *errmsg, size_t errmsg_len)}
4993 @item @emph{Arguments}:
4994 @multitable @columnfractions .15 .70
4995 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4996 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4997 an error message; may be NULL.
4998 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5001 @item @emph{NOTE} A simple implementation could be
5002 @code{__asm__ __volatile__ ("":::"memory")} to prevent code movements.
5007 @node _gfortran_caf_error_stop
5008 @subsection @code{_gfortran_caf_error_stop} --- Error termination with exit code
5009 @cindex Coarray, _gfortran_caf_error_stop
5012 @item @emph{Description}:
5013 Invoked for an @code{ERROR STOP} statement which has an integer argument. The
5014 function should terminate the program with the specified exit code.
5017 @item @emph{Syntax}:
5018 @code{void _gfortran_caf_error_stop (int error)}
5020 @item @emph{Arguments}:
5021 @multitable @columnfractions .15 .70
5022 @item @var{error} @tab intent(in) The exit status to be used.
5028 @node _gfortran_caf_error_stop_str
5029 @subsection @code{_gfortran_caf_error_stop_str} --- Error termination with string
5030 @cindex Coarray, _gfortran_caf_error_stop_str
5033 @item @emph{Description}:
5034 Invoked for an @code{ERROR STOP} statement which has a string as argument. The
5035 function should terminate the program with a nonzero-exit code.
5037 @item @emph{Syntax}:
5038 @code{void _gfortran_caf_error_stop (const char *string, size_t len)}
5040 @item @emph{Arguments}:
5041 @multitable @columnfractions .15 .70
5042 @item @var{string} @tab intent(in) the error message (not zero terminated)
5043 @item @var{len} @tab intent(in) the length of the string
5049 @node _gfortran_caf_fail_image
5050 @subsection @code{_gfortran_caf_fail_image} --- Mark the image failed and end its execution
5051 @cindex Coarray, _gfortran_caf_fail_image
5054 @item @emph{Description}:
5055 Invoked for an @code{FAIL IMAGE} statement. The function should terminate the
5058 @item @emph{Syntax}:
5059 @code{void _gfortran_caf_fail_image ()}
5062 This function follows TS18508.
5067 @node _gfortran_caf_atomic_define
5068 @subsection @code{_gfortran_caf_atomic_define} --- Atomic variable assignment
5069 @cindex Coarray, _gfortran_caf_atomic_define
5072 @item @emph{Description}:
5073 Assign atomically a value to an integer or logical variable.
5075 @item @emph{Syntax}:
5076 @code{void _gfortran_caf_atomic_define (caf_token_t token, size_t offset,
5077 int image_index, void *value, int *stat, int type, int kind)}
5079 @item @emph{Arguments}:
5080 @multitable @columnfractions .15 .70
5081 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5082 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5083 shifted compared to the base address of the coarray.
5084 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5085 positive number; zero indicates the current image when used noncoindexed.
5086 @item @var{value} @tab intent(in) the value to be assigned, passed by reference
5087 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5088 @item @var{type} @tab intent(in) The data type, i.e. @code{BT_INTEGER} (1) or
5089 @code{BT_LOGICAL} (2).
5090 @item @var{kind} @tab intent(in) The kind value (only 4; always @code{int})
5096 @node _gfortran_caf_atomic_ref
5097 @subsection @code{_gfortran_caf_atomic_ref} --- Atomic variable reference
5098 @cindex Coarray, _gfortran_caf_atomic_ref
5101 @item @emph{Description}:
5102 Reference atomically a value of a kind-4 integer or logical variable.
5104 @item @emph{Syntax}:
5105 @code{void _gfortran_caf_atomic_ref (caf_token_t token, size_t offset,
5106 int image_index, void *value, int *stat, int type, int kind)}
5108 @item @emph{Arguments}:
5109 @multitable @columnfractions .15 .70
5110 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5111 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5112 shifted compared to the base address of the coarray.
5113 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5114 positive number; zero indicates the current image when used noncoindexed.
5115 @item @var{value} @tab intent(out) The variable assigned the atomically
5116 referenced variable.
5117 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5118 @item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
5119 @code{BT_LOGICAL} (2).
5120 @item @var{kind} @tab The kind value (only 4; always @code{int})
5126 @node _gfortran_caf_atomic_cas
5127 @subsection @code{_gfortran_caf_atomic_cas} --- Atomic compare and swap
5128 @cindex Coarray, _gfortran_caf_atomic_cas
5131 @item @emph{Description}:
5132 Atomic compare and swap of a kind-4 integer or logical variable. Assigns
5133 atomically the specified value to the atomic variable, if the latter has
5134 the value specified by the passed condition value.
5136 @item @emph{Syntax}:
5137 @code{void _gfortran_caf_atomic_cas (caf_token_t token, size_t offset,
5138 int image_index, void *old, void *compare, void *new_val, int *stat,
5139 int type, int kind)}
5141 @item @emph{Arguments}:
5142 @multitable @columnfractions .15 .70
5143 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5144 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5145 shifted compared to the base address of the coarray.
5146 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5147 positive number; zero indicates the current image when used noncoindexed.
5148 @item @var{old} @tab intent(out) The value which the atomic variable had
5149 just before the cas operation.
5150 @item @var{compare} @tab intent(in) The value used for comparision.
5151 @item @var{new_val} @tab intent(in) The new value for the atomic variable,
5152 assigned to the atomic variable, if @code{compare} equals the value of the
5154 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5155 @item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or
5156 @code{BT_LOGICAL} (2).
5157 @item @var{kind} @tab intent(in) The kind value (only 4; always @code{int})
5163 @node _gfortran_caf_atomic_op
5164 @subsection @code{_gfortran_caf_atomic_op} --- Atomic operation
5165 @cindex Coarray, _gfortran_caf_atomic_op
5168 @item @emph{Description}:
5169 Apply an operation atomically to an atomic integer or logical variable.
5170 After the operation, @var{old} contains the value just before the operation,
5171 which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the @code{value} to
5172 the atomic integer variable or does a bitwise AND, OR or exclusive OR
5173 between the atomic variable and @var{value}; the result is then stored in the
5176 @item @emph{Syntax}:
5177 @code{void _gfortran_caf_atomic_op (int op, caf_token_t token, size_t offset,
5178 int image_index, void *value, void *old, int *stat, int type, int kind)}
5180 @item @emph{Arguments}:
5181 @multitable @columnfractions .15 .70
5182 @item @var{op} @tab intent(in) the operation to be performed; possible values
5183 @code{GFC_CAF_ATOMIC_ADD} (1), @code{GFC_CAF_ATOMIC_AND} (2),
5184 @code{GFC_CAF_ATOMIC_OR} (3), @code{GFC_CAF_ATOMIC_XOR} (4).
5185 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5186 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5187 shifted compared to the base address of the coarray.
5188 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5189 positive number; zero indicates the current image when used noncoindexed.
5190 @item @var{old} @tab intent(out) The value which the atomic variable had
5191 just before the atomic operation.
5192 @item @var{val} @tab intent(in) The new value for the atomic variable,
5193 assigned to the atomic variable, if @code{compare} equals the value of the
5195 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5196 @item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or
5197 @code{BT_LOGICAL} (2)
5198 @item @var{kind} @tab intent(in) the kind value (only 4; always @code{int})
5205 @node _gfortran_caf_co_broadcast
5206 @subsection @code{_gfortran_caf_co_broadcast} --- Sending data to all images
5207 @cindex Coarray, _gfortran_caf_co_broadcast
5210 @item @emph{Description}:
5211 Distribute a value from a given image to all other images in the team. Has to
5212 be called collectively.
5214 @item @emph{Syntax}:
5215 @code{void _gfortran_caf_co_broadcast (gfc_descriptor_t *a,
5216 int source_image, int *stat, char *errmsg, size_t errmsg_len)}
5218 @item @emph{Arguments}:
5219 @multitable @columnfractions .15 .70
5220 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5221 broadcasted (on @var{source_image}) or to be received (other images).
5222 @item @var{source_image} @tab intent(in) The ID of the image from which the
5223 data should be broadcasted.
5224 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5225 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5226 an error message; may be NULL.
5227 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg.
5233 @node _gfortran_caf_co_max
5234 @subsection @code{_gfortran_caf_co_max} --- Collective maximum reduction
5235 @cindex Coarray, _gfortran_caf_co_max
5238 @item @emph{Description}:
5239 Calculates for each array element of the variable @var{a} the maximum
5240 value for that element in the current team; if @var{result_image} has the
5241 value 0, the result shall be stored on all images, otherwise, only on the
5242 specified image. This function operates on numeric values and character
5245 @item @emph{Syntax}:
5246 @code{void _gfortran_caf_co_max (gfc_descriptor_t *a, int result_image,
5247 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5249 @item @emph{Arguments}:
5250 @multitable @columnfractions .15 .70
5251 @item @var{a} @tab intent(inout) An array descriptor for the data to be
5252 processed. On the destination image(s) the result overwrites the old content.
5253 @item @var{result_image} @tab intent(in) The ID of the image to which the
5254 reduced value should be copied to; if zero, it has to be copied to all images.
5255 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5256 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5257 an error message; may be NULL.
5258 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5259 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5263 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5264 all images except of the specified one become undefined; hence, the library may
5270 @node _gfortran_caf_co_min
5271 @subsection @code{_gfortran_caf_co_min} --- Collective minimum reduction
5272 @cindex Coarray, _gfortran_caf_co_min
5275 @item @emph{Description}:
5276 Calculates for each array element of the variable @var{a} the minimum
5277 value for that element in the current team; if @var{result_image} has the
5278 value 0, the result shall be stored on all images, otherwise, only on the
5279 specified image. This function operates on numeric values and character
5282 @item @emph{Syntax}:
5283 @code{void _gfortran_caf_co_min (gfc_descriptor_t *a, int result_image,
5284 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5286 @item @emph{Arguments}:
5287 @multitable @columnfractions .15 .70
5288 @item @var{a} @tab intent(inout) An array descriptor for the data to be
5289 processed. On the destination image(s) the result overwrites the old content.
5290 @item @var{result_image} @tab intent(in) The ID of the image to which the
5291 reduced value should be copied to; if zero, it has to be copied to all images.
5292 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5293 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5294 an error message; may be NULL.
5295 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5296 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5300 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5301 all images except of the specified one become undefined; hence, the library may
5307 @node _gfortran_caf_co_sum
5308 @subsection @code{_gfortran_caf_co_sum} --- Collective summing reduction
5309 @cindex Coarray, _gfortran_caf_co_sum
5312 @item @emph{Description}:
5313 Calculates for each array element of the variable @var{a} the sum of all
5314 values for that element in the current team; if @var{result_image} has the
5315 value 0, the result shall be stored on all images, otherwise, only on the
5316 specified image. This function operates on numeric values only.
5318 @item @emph{Syntax}:
5319 @code{void _gfortran_caf_co_sum (gfc_descriptor_t *a, int result_image,
5320 int *stat, char *errmsg, size_t errmsg_len)}
5322 @item @emph{Arguments}:
5323 @multitable @columnfractions .15 .70
5324 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5325 processed. On the destination image(s) the result overwrites the old content.
5326 @item @var{result_image} @tab intent(in) The ID of the image to which the
5327 reduced value should be copied to; if zero, it has to be copied to all images.
5328 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5329 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5330 an error message; may be NULL.
5331 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5335 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5336 all images except of the specified one become undefined; hence, the library may
5342 @node _gfortran_caf_co_reduce
5343 @subsection @code{_gfortran_caf_co_reduce} --- Generic collective reduction
5344 @cindex Coarray, _gfortran_caf_co_reduce
5347 @item @emph{Description}:
5348 Calculates for each array element of the variable @var{a} the reduction
5349 value for that element in the current team; if @var{result_image} has the
5350 value 0, the result shall be stored on all images, otherwise, only on the
5351 specified image. The @var{opr} is a pure function doing a mathematically
5352 commutative and associative operation.
5354 The @var{opr_flags} denote the following; the values are bitwise ored.
5355 @code{GFC_CAF_BYREF} (1) if the result should be returned
5356 by reference; @code{GFC_CAF_HIDDENLEN} (2) whether the result and argument
5357 string lengths shall be specified as hidden arguments;
5358 @code{GFC_CAF_ARG_VALUE} (4) whether the arguments shall be passed by value,
5359 @code{GFC_CAF_ARG_DESC} (8) whether the arguments shall be passed by descriptor.
5362 @item @emph{Syntax}:
5363 @code{void _gfortran_caf_co_reduce (gfc_descriptor_t *a,
5364 void * (*opr) (void *, void *), int opr_flags, int result_image,
5365 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5367 @item @emph{Arguments}:
5368 @multitable @columnfractions .15 .70
5369 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5370 processed. On the destination image(s) the result overwrites the old content.
5371 @item @var{opr} @tab intent(in) Function pointer to the reduction function
5372 @item @var{opr_flags} @tab intent(in) Flags regarding the reduction function
5373 @item @var{result_image} @tab intent(in) The ID of the image to which the
5374 reduced value should be copied to; if zero, it has to be copied to all images.
5375 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5376 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5377 an error message; may be NULL.
5378 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5379 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5383 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5384 all images except of the specified one become undefined; hence, the library may
5387 For character arguments, the result is passed as first argument, followed
5388 by the result string length, next come the two string arguments, followed
5389 by the two hidden string length arguments. With C binding, there are no hidden
5390 arguments and by-reference passing and either only a single character is passed
5391 or an array descriptor.
5395 @c Intrinsic Procedures
5396 @c ---------------------------------------------------------------------
5398 @include intrinsic.texi
5405 @c ---------------------------------------------------------------------
5407 @c ---------------------------------------------------------------------
5410 @unnumbered Contributing
5411 @cindex Contributing
5413 Free software is only possible if people contribute to efforts
5415 We're always in need of more people helping out with ideas
5416 and comments, writing documentation and contributing code.
5418 If you want to contribute to GNU Fortran,
5419 have a look at the long lists of projects you can take on.
5420 Some of these projects are small,
5421 some of them are large;
5422 some are completely orthogonal to the rest of what is
5423 happening on GNU Fortran,
5424 but others are ``mainstream'' projects in need of enthusiastic hackers.
5425 All of these projects are important!
5426 We will eventually get around to the things here,
5427 but they are also things doable by someone who is willing and able.
5436 @section Contributors to GNU Fortran
5437 @cindex Contributors
5441 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
5442 also the initiator of the whole project. Thanks Andy!
5443 Most of the interface with GCC was written by @emph{Paul Brook}.
5445 The following individuals have contributed code and/or
5446 ideas and significant help to the GNU Fortran project
5447 (in alphabetical order):
5450 @item Janne Blomqvist
5451 @item Steven Bosscher
5454 @item Fran@,{c}ois-Xavier Coudert
5458 @item Bernhard Fischer
5460 @item Richard Guenther
5461 @item Richard Henderson
5462 @item Katherine Holcomb
5464 @item Niels Kristian Bech Jensen
5465 @item Steven Johnson
5466 @item Steven G. Kargl
5474 @item Christopher D. Rickett
5475 @item Richard Sandiford
5476 @item Tobias Schl@"uter
5485 The following people have contributed bug reports,
5486 smaller or larger patches,
5487 and much needed feedback and encouragement for the
5488 GNU Fortran project:
5492 @item Dominique d'Humi@`eres
5494 @item Erik Schnetter
5495 @item Gerhard Steinmetz
5496 @item Joost VandeVondele
5499 Many other individuals have helped debug,
5500 test and improve the GNU Fortran compiler over the past few years,
5501 and we welcome you to do the same!
5502 If you already have done so,
5503 and you would like to see your name listed in the
5504 list above, please contact us.
5512 @item Help build the test suite
5513 Solicit more code for donation to the test suite: the more extensive the
5514 testsuite, the smaller the risk of breaking things in the future! We can
5515 keep code private on request.
5517 @item Bug hunting/squishing
5518 Find bugs and write more test cases! Test cases are especially very
5519 welcome, because it allows us to concentrate on fixing bugs instead of
5520 isolating them. Going through the bugzilla database at
5521 @url{https://gcc.gnu.org/@/bugzilla/} to reduce testcases posted there and
5522 add more information (for example, for which version does the testcase
5523 work, for which versions does it fail?) is also very helpful.
5525 @item Missing features
5526 For a larger project, consider working on the missing features required for
5527 Fortran language standards compliance (@pxref{Standards}), or contributing
5528 to the implementation of extensions such as OpenMP (@pxref{OpenMP}) or
5529 OpenACC (@pxref{OpenACC}) that are under active development. Again,
5530 contributing test cases for these features is useful too!
5535 @c ---------------------------------------------------------------------
5536 @c GNU General Public License
5537 @c ---------------------------------------------------------------------
5539 @include gpl_v3.texi
5543 @c ---------------------------------------------------------------------
5544 @c GNU Free Documentation License
5545 @c ---------------------------------------------------------------------
5551 @c ---------------------------------------------------------------------
5552 @c Funding Free Software
5553 @c ---------------------------------------------------------------------
5555 @include funding.texi
5557 @c ---------------------------------------------------------------------
5559 @c ---------------------------------------------------------------------
5562 @unnumbered Option Index
5563 @command{gfortran}'s command line options are indexed here without any
5564 initial @samp{-} or @samp{--}. Where an option has both positive and
5565 negative forms (such as -foption and -fno-option), relevant entries in
5566 the manual are indexed under the most appropriate form; it may sometimes
5567 be useful to look up both forms.
5571 @unnumbered Keyword Index