1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set copyrights-gfortran 1999-2023
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 Mac OS X. 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 * Extended math intrinsics::
1243 * Form feed as whitespace::
1244 * TYPE as an alias for PRINT::
1245 * %LOC as an rvalue::
1247 * Bitwise logical operators::
1248 * Extended I/O specifiers::
1249 * Legacy PARAMETER statements::
1250 * Default exponents::
1253 @node Old-style kind specifications
1254 @subsection Old-style kind specifications
1255 @cindex kind, old-style
1257 GNU Fortran allows old-style kind specifications in declarations. These
1263 where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
1264 etc.), and where @code{size} is a byte count corresponding to the
1265 storage size of a valid kind for that type. (For @code{COMPLEX}
1266 variables, @code{size} is the total size of the real and imaginary
1267 parts.) The statement then declares @code{x}, @code{y} and @code{z} to
1268 be of type @code{TYPESPEC} with the appropriate kind. This is
1269 equivalent to the standard-conforming declaration
1274 where @code{k} is the kind parameter suitable for the intended precision. As
1275 kind parameters are implementation-dependent, use the @code{KIND},
1276 @code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve
1277 the correct value, for instance @code{REAL*8 x} can be replaced by:
1279 INTEGER, PARAMETER :: dbl = KIND(1.0d0)
1283 @node Old-style variable initialization
1284 @subsection Old-style variable initialization
1286 GNU Fortran allows old-style initialization of variables of the
1290 REAL x(2,2) /3*0.,1./
1292 The syntax for the initializers is as for the @code{DATA} statement, but
1293 unlike in a @code{DATA} statement, an initializer only applies to the
1294 variable immediately preceding the initialization. In other words,
1295 something like @code{INTEGER I,J/2,3/} is not valid. This style of
1296 initialization is only allowed in declarations without double colons
1297 (@code{::}); the double colons were introduced in Fortran 90, which also
1298 introduced a standard syntax for initializing variables in type
1301 Examples of standard-conforming code equivalent to the above example
1305 INTEGER :: i = 1, j = 2
1306 REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
1310 DATA i/1/, j/2/, x/3*0.,1./
1313 Note that variables which are explicitly initialized in declarations
1314 or in @code{DATA} statements automatically acquire the @code{SAVE}
1317 @node Extensions to namelist
1318 @subsection Extensions to namelist
1321 GNU Fortran fully supports the Fortran 95 standard for namelist I/O
1322 including array qualifiers, substrings and fully qualified derived types.
1323 The output from a namelist write is compatible with namelist read. The
1324 output has all names in upper case and indentation to column 1 after the
1325 namelist name. Two extensions are permitted:
1327 Old-style use of @samp{$} instead of @samp{&}
1330 X(:)%Y(2) = 1.0 2.0 3.0
1335 It should be noted that the default terminator is @samp{/} rather than
1338 Querying of the namelist when inputting from stdin. After at least
1339 one space, entering @samp{?} sends to stdout the namelist name and the names of
1340 the variables in the namelist:
1351 Entering @samp{=?} outputs the namelist to stdout, as if
1352 @code{WRITE(*,NML = mynml)} had been called:
1357 X(1)%Y= 0.000000 , 1.000000 , 0.000000 ,
1358 X(2)%Y= 0.000000 , 2.000000 , 0.000000 ,
1359 X(3)%Y= 0.000000 , 3.000000 , 0.000000 ,
1363 To aid this dialog, when input is from stdin, errors send their
1364 messages to stderr and execution continues, even if @code{IOSTAT} is set.
1366 @code{PRINT} namelist is permitted. This causes an error if
1367 @option{-std=f95} is used.
1370 REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/)
1373 END PROGRAM test_print
1376 Expanded namelist reads are permitted. This causes an error if
1377 @option{-std=f95} is used. In the following example, the first element
1378 of the array will be given the value 0.00 and the two succeeding
1379 elements will be given the values 1.00 and 2.00.
1382 X(1,1) = 0.00 , 1.00 , 2.00
1386 When writing a namelist, if no @code{DELIM=} is specified, by default a
1387 double quote is used to delimit character strings. If -std=F95, F2003,
1388 or F2008, etc, the delim status is set to 'none'. Defaulting to
1389 quotes ensures that namelists with character strings can be subsequently
1390 read back in accurately.
1392 @node X format descriptor without count field
1393 @subsection @code{X} format descriptor without count field
1395 To support legacy codes, GNU Fortran permits the count field of the
1396 @code{X} edit descriptor in @code{FORMAT} statements to be omitted.
1397 When omitted, the count is implicitly assumed to be one.
1401 10 FORMAT (I1, X, I1)
1404 @node Commas in FORMAT specifications
1405 @subsection Commas in @code{FORMAT} specifications
1407 To support legacy codes, GNU Fortran allows the comma separator
1408 to be omitted immediately before and after character string edit
1409 descriptors in @code{FORMAT} statements. A comma with no following format
1410 descriptor is permitted if the @option{-fdec-blank-format-item} is given on
1411 the command line. This is considered non-conforming code and is
1416 10 FORMAT ('FOO='I1' BAR='I2)
1422 @node Missing period in FORMAT specifications
1423 @subsection Missing period in @code{FORMAT} specifications
1425 To support legacy codes, GNU Fortran allows missing periods in format
1426 specifications if and only if @option{-std=legacy} is given on the
1427 command line. This is considered non-conforming code and is
1436 @node Default widths for F@comma{} G and I format descriptors
1437 @subsection Default widths for @code{F}, @code{G} and @code{I} format descriptors
1439 To support legacy codes, GNU Fortran allows width to be omitted from format
1440 specifications if and only if @option{-fdec-format-defaults} is given on the
1441 command line. Default widths will be used. This is considered non-conforming
1442 code and is discouraged.
1447 WRITE(*,10) value1, value1, value2
1448 10 FORMAT ('F, G, I')
1452 @node I/O item lists
1453 @subsection I/O item lists
1454 @cindex I/O item lists
1456 To support legacy codes, GNU Fortran allows the input item list
1457 of the @code{READ} statement, and the output item lists of the
1458 @code{WRITE} and @code{PRINT} statements, to start with a comma.
1460 @node @code{Q} exponent-letter
1461 @subsection @code{Q} exponent-letter
1462 @cindex @code{Q} exponent-letter
1464 GNU Fortran accepts real literal constants with an exponent-letter
1465 of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted
1466 as a @code{REAL(16)} entity on targets that support this type. If
1467 the target does not support @code{REAL(16)} but has a @code{REAL(10)}
1468 type, then the real-literal-constant will be interpreted as a
1469 @code{REAL(10)} entity. In the absence of @code{REAL(16)} and
1470 @code{REAL(10)}, an error will occur.
1472 @node BOZ literal constants
1473 @subsection BOZ literal constants
1474 @cindex BOZ literal constants
1476 Besides decimal constants, Fortran also supports binary (@code{b}),
1477 octal (@code{o}) and hexadecimal (@code{z}) integer constants. The
1478 syntax is: @samp{prefix quote digits quote}, where the prefix is
1479 either @code{b}, @code{o} or @code{z}, quote is either @code{'} or
1480 @code{"} and the digits are @code{0} or @code{1} for binary,
1481 between @code{0} and @code{7} for octal, and between @code{0} and
1482 @code{F} for hexadecimal. (Example: @code{b'01011101'}.)
1484 Up to Fortran 95, BOZ literal constants were only allowed to initialize
1485 integer variables in DATA statements. Since Fortran 2003 BOZ literal
1486 constants are also allowed as actual arguments to the @code{REAL},
1487 @code{DBLE}, @code{INT} and @code{CMPLX} intrinsic functions.
1488 The BOZ literal constant is simply a string of bits, which is padded
1489 or truncated as needed, during conversion to a numeric type. The
1490 Fortran standard states that the treatment of the sign bit is processor
1491 dependent. Gfortran interprets the sign bit as a user would expect.
1493 As a deprecated extension, GNU Fortran allows hexadecimal BOZ literal
1494 constants to be specified using the @code{X} prefix. That the BOZ literal
1495 constant can also be specified by adding a suffix to the string, for
1496 example, @code{Z'ABC'} and @code{'ABC'X} are equivalent. Additionally,
1497 as extension, BOZ literals are permitted in some contexts outside of
1498 @code{DATA} and the intrinsic functions listed in the Fortran standard.
1499 Use @option{-fallow-invalid-boz} to enable the extension.
1501 @node Real array indices
1502 @subsection Real array indices
1503 @cindex array, indices of type real
1505 As an extension, GNU Fortran allows the use of @code{REAL} expressions
1506 or variables as array indices.
1508 @node Unary operators
1509 @subsection Unary operators
1510 @cindex operators, unary
1512 As an extension, GNU Fortran allows unary plus and unary minus operators
1513 to appear as the second operand of binary arithmetic operators without
1514 the need for parenthesis.
1520 @node Implicitly convert LOGICAL and INTEGER values
1521 @subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values
1522 @cindex conversion, to integer
1523 @cindex conversion, to logical
1525 As an extension for backwards compatibility with other compilers, GNU
1526 Fortran allows the implicit conversion of @code{LOGICAL} values to
1527 @code{INTEGER} values and vice versa. When converting from a
1528 @code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as
1529 zero, and @code{.TRUE.} is interpreted as one. When converting from
1530 @code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as
1531 @code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}.
1542 However, there is no implicit conversion of @code{INTEGER} values in
1543 @code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values
1546 @node Hollerith constants support
1547 @subsection Hollerith constants support
1548 @cindex Hollerith constants
1550 GNU Fortran supports Hollerith constants in assignments, @code{DATA}
1551 statements, function and subroutine arguments. A Hollerith constant is
1552 written as a string of characters preceded by an integer constant
1553 indicating the character count, and the letter @code{H} or
1554 @code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER},
1555 @code{REAL}, or @code{COMPLEX}), @code{LOGICAL} or @code{CHARACTER} variable.
1556 The constant will be padded with spaces or truncated to fit the size of
1557 the variable in which it is stored.
1559 Examples of valid uses of Hollerith constants:
1562 data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/
1563 x(1) = 16HABCDEFGHIJKLMNOP
1567 Examples of Hollerith constants:
1570 a = 0H ! Invalid, at least one character is needed.
1572 a = 8H12345678 ! Valid, but the Hollerith constant will be truncated.
1573 a = 3Hxyz ! Valid, but the Hollerith constant will be padded.
1576 In general, Hollerith constants were used to provide a rudimentary
1577 facility for handling character strings in early Fortran compilers,
1578 prior to the introduction of @code{CHARACTER} variables in Fortran 77;
1579 in those cases, the standard-compliant equivalent is to convert the
1580 program to use proper character strings. On occasion, there may be a
1581 case where the intent is specifically to initialize a numeric variable
1582 with a given byte sequence. In these cases, the same result can be
1583 obtained by using the @code{TRANSFER} statement, as in this example.
1585 integer(kind=4) :: a
1586 a = transfer ("abcd", a) ! equivalent to: a = 4Habcd
1589 The use of the @option{-fdec} option extends support of Hollerith constants
1594 if (a .ne. 4habcd) then
1595 write(*,*) "no match"
1599 Supported types are numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}),
1600 and @code{CHARACTER}.
1602 @node Character conversion
1603 @subsection Character conversion
1604 @cindex conversion, to character
1606 Allowing character literals to be used in a similar way to Hollerith constants
1607 is a non-standard extension. This feature is enabled using
1608 -fdec-char-conversions and only applies to character literals of @code{kind=1}.
1610 Character literals can be used in @code{DATA} statements and assignments with
1611 numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}) or @code{LOGICAL}
1612 variables. Like Hollerith constants they are copied byte-wise fashion. The
1613 constant will be padded with spaces or truncated to fit the size of the
1614 variable in which it is stored.
1621 x = 'A' ! Will be padded.
1622 x = 'ab1234' ! Will be truncated.
1627 @subsection Cray pointers
1628 @cindex pointer, Cray
1630 Cray pointers are part of a non-standard extension that provides a
1631 C-like pointer in Fortran. This is accomplished through a pair of
1632 variables: an integer "pointer" that holds a memory address, and a
1633 "pointee" that is used to dereference the pointer.
1635 Pointer/pointee pairs are declared in statements of the form:
1637 pointer ( <pointer> , <pointee> )
1641 pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ...
1643 The pointer is an integer that is intended to hold a memory address.
1644 The pointee may be an array or scalar.
1645 If an assumed-size array is permitted within the scoping unit, a
1646 pointee can be an assumed-size array.
1647 That is, the last dimension may be left unspecified by using a @code{*}
1648 in place of a value. A pointee cannot be an assumed shape array.
1649 No space is allocated for the pointee.
1651 The pointee may have its type declared before or after the pointer
1652 statement, and its array specification (if any) may be declared
1653 before, during, or after the pointer statement. The pointer may be
1654 declared as an integer prior to the pointer statement. However, some
1655 machines have default integer sizes that are different than the size
1656 of a pointer, and so the following code is not portable:
1661 If a pointer is declared with a kind that is too small, the compiler
1662 will issue a warning; the resulting binary will probably not work
1663 correctly, because the memory addresses stored in the pointers may be
1664 truncated. It is safer to omit the first line of the above example;
1665 if explicit declaration of ipt's type is omitted, then the compiler
1666 will ensure that ipt is an integer variable large enough to hold a
1669 Pointer arithmetic is valid with Cray pointers, but it is not the same
1670 as C pointer arithmetic. Cray pointers are just ordinary integers, so
1671 the user is responsible for determining how many bytes to add to a
1672 pointer in order to increment it. Consider the following example:
1676 pointer (ipt, pointee)
1680 The last statement does not set @code{ipt} to the address of
1681 @code{target(1)}, as it would in C pointer arithmetic. Adding @code{1}
1682 to @code{ipt} just adds one byte to the address stored in @code{ipt}.
1684 Any expression involving the pointee will be translated to use the
1685 value stored in the pointer as the base address.
1687 To get the address of elements, this extension provides an intrinsic
1688 function @code{LOC()}. The @code{LOC()} function is equivalent to the
1689 @code{&} operator in C, except the address is cast to an integer type:
1692 pointer(ipt, arpte(10))
1694 ipt = loc(ar) ! Makes arpte is an alias for ar
1695 arpte(1) = 1.0 ! Sets ar(1) to 1.0
1697 The pointer can also be set by a call to the @code{MALLOC} intrinsic
1700 Cray pointees often are used to alias an existing variable. For
1708 As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for
1709 @code{target}. The optimizer, however, will not detect this aliasing, so
1710 it is unsafe to use @code{iarr} and @code{target} simultaneously. Using
1711 a pointee in any way that violates the Fortran aliasing rules or
1712 assumptions is illegal. It is the user's responsibility to avoid doing
1713 this; the compiler works under the assumption that no such aliasing
1716 Cray pointers will work correctly when there is no aliasing (i.e., when
1717 they are used to access a dynamically allocated block of memory), and
1718 also in any routine where a pointee is used, but any variable with which
1719 it shares storage is not used. Code that violates these rules may not
1720 run as the user intends. This is not a bug in the optimizer; any code
1721 that violates the aliasing rules is illegal. (Note that this is not
1722 unique to GNU Fortran; any Fortran compiler that supports Cray pointers
1723 will ``incorrectly'' optimize code with illegal aliasing.)
1725 There are a number of restrictions on the attributes that can be applied
1726 to Cray pointers and pointees. Pointees may not have the
1727 @code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY},
1728 @code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers
1729 may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET},
1730 @code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor
1731 may they be function results. Pointees may not occur in more than one
1732 pointer statement. A pointee cannot be a pointer. Pointees cannot occur
1733 in equivalence, common, or data statements.
1735 A Cray pointer may also point to a function or a subroutine. For
1736 example, the following excerpt is valid:
1740 pointer (subptr,subpte)
1750 A pointer may be modified during the course of a program, and this
1751 will change the location to which the pointee refers. However, when
1752 pointees are passed as arguments, they are treated as ordinary
1753 variables in the invoked function. Subsequent changes to the pointer
1754 will not change the base address of the array that was passed.
1756 @node CONVERT specifier
1757 @subsection @code{CONVERT} specifier
1758 @cindex @code{CONVERT} specifier
1760 GNU Fortran allows the conversion of unformatted data between little-
1761 and big-endian representation to facilitate moving of data
1762 between different systems. The conversion can be indicated with
1763 the @code{CONVERT} specifier on the @code{OPEN} statement.
1764 @xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying
1765 the data format via an environment variable.
1767 Valid values for @code{CONVERT} on most systems are:
1769 @item @code{CONVERT='NATIVE'} Use the native format. This is the default.
1770 @item @code{CONVERT='SWAP'} Swap between little- and big-endian.
1771 @item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation
1772 for unformatted files.
1773 @item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for
1776 On POWER systems which support @option{-mabi=ieeelongdouble},
1777 there are additional options, which can be combined with the others
1778 with commas. Those are
1780 @item @code{CONVERT='R16_IEEE'} Use IEEE 128-bit format for
1781 @code{REAL(KIND=16)}.
1782 @item @code{CONVERT='R16_IBM'} Use IBM @code{long double} format for
1783 real@code{REAL(KIND=16)}.
1786 Using the option could look like this:
1788 open(file='big.dat',form='unformatted',access='sequential', &
1789 convert='big_endian')
1792 The value of the conversion can be queried by using
1793 @code{INQUIRE(CONVERT=ch)}. The values returned are
1794 @code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}.
1796 @code{CONVERT} works between big- and little-endian for
1797 @code{INTEGER} values of all supported kinds and for @code{REAL}
1798 on IEEE systems of kinds 4 and 8. Conversion between different
1799 ``extended double'' types on different architectures such as
1800 m68k and x86_64, which GNU Fortran
1801 supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will
1804 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
1805 environment variable will override the CONVERT specifier in the
1806 open statement}. This is to give control over data formats to
1807 users who do not have the source code of their program available.
1809 Using anything but the native representation for unformatted data
1810 carries a significant speed overhead. If speed in this area matters
1811 to you, it is best if you use this only for data that needs to be
1818 OpenMP (Open Multi-Processing) is an application programming
1819 interface (API) that supports multi-platform shared memory
1820 multiprocessing programming in C/C++ and Fortran on many
1821 architectures, including Unix and Microsoft Windows platforms.
1822 It consists of a set of compiler directives, library routines,
1823 and environment variables that influence run-time behavior.
1825 GNU Fortran strives to be compatible to the
1826 @uref{https://openmp.org/specifications/,
1827 OpenMP Application Program Interface v4.5}.
1829 To enable the processing of the OpenMP directive @code{!$omp} in
1830 free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp}
1831 directives in fixed form; the @code{!$} conditional compilation sentinels
1832 in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels
1833 in fixed form, @command{gfortran} needs to be invoked with the
1834 @option{-fopenmp}. This also arranges for automatic linking of the
1835 GNU Offloading and Multi Processing Runtime Library
1836 @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
1839 The OpenMP Fortran runtime library routines are provided both in a
1840 form of a Fortran 90 module named @code{omp_lib} and in a form of
1841 a Fortran @code{include} file named @file{omp_lib.h}.
1843 An example of a parallelized loop taken from Appendix A.1 of
1844 the OpenMP Application Program Interface v2.5:
1846 SUBROUTINE A1(N, A, B)
1849 !$OMP PARALLEL DO !I is private by default
1851 B(I) = (A(I) + A(I-1)) / 2.0
1853 !$OMP END PARALLEL DO
1860 @option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays
1861 will be allocated on the stack. When porting existing code to OpenMP,
1862 this may lead to surprising results, especially to segmentation faults
1863 if the stacksize is limited.
1866 On glibc-based systems, OpenMP enabled applications cannot be statically
1867 linked due to limitations of the underlying pthreads-implementation. It
1868 might be possible to get a working solution if
1869 @command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added
1870 to the command line. However, this is not supported by @command{gcc} and
1871 thus not recommended.
1878 OpenACC is an application programming interface (API) that supports
1879 offloading of code to accelerator devices. It consists of a set of
1880 compiler directives, library routines, and environment variables that
1881 influence run-time behavior.
1883 GNU Fortran strives to be compatible to the
1884 @uref{https://www.openacc.org/, OpenACC Application Programming
1887 To enable the processing of the OpenACC directive @code{!$acc} in
1888 free-form source code; the @code{c$acc}, @code{*$acc} and @code{!$acc}
1889 directives in fixed form; the @code{!$} conditional compilation
1890 sentinels in free form; and the @code{c$}, @code{*$} and @code{!$}
1891 sentinels in fixed form, @command{gfortran} needs to be invoked with
1892 the @option{-fopenacc}. This also arranges for automatic linking of
1893 the GNU Offloading and Multi Processing Runtime Library
1894 @ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime
1897 The OpenACC Fortran runtime library routines are provided both in a
1898 form of a Fortran 90 module named @code{openacc} and in a form of a
1899 Fortran @code{include} file named @file{openacc_lib.h}.
1901 @node Argument list functions
1902 @subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC}
1903 @cindex argument list functions
1908 GNU Fortran supports argument list functions @code{%VAL}, @code{%REF}
1909 and @code{%LOC} statements, for backward compatibility with g77.
1910 It is recommended that these should be used only for code that is
1911 accessing facilities outside of GNU Fortran, such as operating system
1912 or windowing facilities. It is best to constrain such uses to isolated
1913 portions of a program--portions that deal specifically and exclusively
1914 with low-level, system-dependent facilities. Such portions might well
1915 provide a portable interface for use by the program as a whole, but are
1916 themselves not portable, and should be thoroughly tested each time they
1917 are rebuilt using a new compiler or version of a compiler.
1919 @code{%VAL} passes a scalar argument by value, @code{%REF} passes it by
1920 reference and @code{%LOC} passes its memory location. Since gfortran
1921 already passes scalar arguments by reference, @code{%REF} is in effect
1922 a do-nothing. @code{%LOC} has the same effect as a Fortran pointer.
1924 An example of passing an argument by value to a C subroutine foo.:
1927 C prototype void foo_ (float x);
1936 For details refer to the g77 manual
1937 @uref{https://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}.
1939 Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the
1940 GNU Fortran testsuite are worth a look.
1942 @node Read/Write after EOF marker
1943 @subsection Read/Write after EOF marker
1945 @cindex @code{BACKSPACE}
1946 @cindex @code{REWIND}
1948 Some legacy codes rely on allowing @code{READ} or @code{WRITE} after the
1949 EOF file marker in order to find the end of a file. GNU Fortran normally
1950 rejects these codes with a run-time error message and suggests the user
1951 consider @code{BACKSPACE} or @code{REWIND} to properly position
1952 the file before the EOF marker. As an extension, the run-time error may
1953 be disabled using -std=legacy.
1956 @node STRUCTURE and RECORD
1957 @subsection @code{STRUCTURE} and @code{RECORD}
1958 @cindex @code{STRUCTURE}
1959 @cindex @code{RECORD}
1961 Record structures are a pre-Fortran-90 vendor extension to create
1962 user-defined aggregate data types. Support for record structures in GNU
1963 Fortran can be enabled with the @option{-fdec-structure} compile flag.
1964 If you have a choice, you should instead use Fortran 90's ``derived types'',
1965 which have a different syntax.
1967 In many cases, record structures can easily be converted to derived types.
1968 To convert, replace @code{STRUCTURE /}@var{structure-name}@code{/}
1969 by @code{TYPE} @var{type-name}. Additionally, replace
1970 @code{RECORD /}@var{structure-name}@code{/} by
1971 @code{TYPE(}@var{type-name}@code{)}. Finally, in the component access,
1972 replace the period (@code{.}) by the percent sign (@code{%}).
1974 Here is an example of code using the non portable record structure syntax:
1977 ! Declaring a structure named ``item'' and containing three fields:
1978 ! an integer ID, an description string and a floating-point price.
1981 CHARACTER(LEN=200) description
1985 ! Define two variables, an single record of type ``item''
1986 ! named ``pear'', and an array of items named ``store_catalog''
1987 RECORD /item/ pear, store_catalog(100)
1989 ! We can directly access the fields of both variables
1991 pear.description = "juicy D'Anjou pear"
1993 store_catalog(7).id = 7831
1994 store_catalog(7).description = "milk bottle"
1995 store_catalog(7).price = 1.2
1997 ! We can also manipulate the whole structure
1998 store_catalog(12) = pear
1999 print *, store_catalog(12)
2003 This code can easily be rewritten in the Fortran 90 syntax as following:
2006 ! ``STRUCTURE /name/ ... END STRUCTURE'' becomes
2007 ! ``TYPE name ... END TYPE''
2010 CHARACTER(LEN=200) description
2014 ! ``RECORD /name/ variable'' becomes ``TYPE(name) variable''
2015 TYPE(item) pear, store_catalog(100)
2017 ! Instead of using a dot (.) to access fields of a record, the
2018 ! standard syntax uses a percent sign (%)
2020 pear%description = "juicy D'Anjou pear"
2022 store_catalog(7)%id = 7831
2023 store_catalog(7)%description = "milk bottle"
2024 store_catalog(7)%price = 1.2
2026 ! Assignments of a whole variable do not change
2027 store_catalog(12) = pear
2028 print *, store_catalog(12)
2032 GNU Fortran implements STRUCTURES like derived types with the following
2033 rules and exceptions:
2036 @item Structures act like derived types with the @code{SEQUENCE} attribute.
2037 Otherwise they may contain no specifiers.
2039 @item Structures may contain a special field with the name @code{%FILL}.
2040 This will create an anonymous component which cannot be accessed but occupies
2041 space just as if a component of the same type was declared in its place, useful
2042 for alignment purposes. As an example, the following structure will consist
2043 of at least sixteen bytes:
2053 @item Structures may share names with other symbols. For example, the following
2054 is invalid for derived types, but valid for structures:
2060 record /header/ header
2063 @item Structure types may be declared nested within another parent structure.
2066 structure /type-name/
2068 structure [/<type-name>/] <field-list>
2072 The type name may be ommitted, in which case the structure type itself is
2073 anonymous, and other structures of the same type cannot be instantiated. The
2074 following shows some examples:
2077 structure /appointment/
2078 ! nested structure definition: app_time is an array of two 'time'
2079 structure /time/ app_time (2)
2080 integer(1) hour, minute
2085 ! The 'time' structure is still usable
2091 structure /appointment/
2092 ! anonymous nested structure definition
2093 structure start, end
2094 integer(1) hour, minute
2100 @item Structures may contain @code{UNION} blocks. For more detail see the
2101 section on @ref{UNION and MAP}.
2103 @item Structures support old-style initialization of components, like
2104 those described in @ref{Old-style variable initialization}. For array
2105 initializers, an initializer may contain a repeat specification of the form
2106 @code{<literal-integer> * <constant-initializer>}. The value of the integer
2107 indicates the number of times to repeat the constant initializer when expanding
2108 the initializer list.
2112 @subsection @code{UNION} and @code{MAP}
2113 @cindex @code{UNION}
2116 Unions are an old vendor extension which were commonly used with the
2117 non-standard @ref{STRUCTURE and RECORD} extensions. Use of @code{UNION} and
2118 @code{MAP} is automatically enabled with @option{-fdec-structure}.
2120 A @code{UNION} declaration occurs within a structure; within the definition of
2121 each union is a number of @code{MAP} blocks. Each @code{MAP} shares storage
2122 with its sibling maps (in the same union), and the size of the union is the
2123 size of the largest map within it, just as with unions in C. The major
2124 difference is that component references do not indicate which union or map the
2125 component is in (the compiler gets to figure that out).
2127 Here is a small example:
2132 character(2) w0, w1, w2
2140 record /myunion/ rec
2141 ! After this assignment...
2144 ! The following is true:
2150 The two maps share memory, and the size of the union is ultimately six bytes:
2153 0 1 2 3 4 5 6 Byte offset
2154 -------------------------------
2156 -------------------------------
2159 \-------/ \-------/ \-------/
2162 \---------------------------/
2165 Following is an example mirroring the layout of an Intel x86_64 register:
2174 character(8) rh ! rah
2177 character(8) rl ! ral
2180 character(8) ex ! eax
2183 character(4) eh ! eah
2186 character(4) el ! eal
2203 ! After this assignment...
2204 a.rx = 'AAAAAAAA.BBB.C.D'
2206 ! The following is true:
2207 a.rx === 'AAAAAAAA.BBB.C.D'
2218 @node Type variants for integer intrinsics
2219 @subsection Type variants for integer intrinsics
2220 @cindex intrinsics, integer
2222 Similar to the D/C prefixes to real functions to specify the input/output
2223 types, GNU Fortran offers B/I/J/K prefixes to integer functions for
2224 compatibility with DEC programs. The types implied by each are:
2227 @code{B} - @code{INTEGER(kind=1)}
2228 @code{I} - @code{INTEGER(kind=2)}
2229 @code{J} - @code{INTEGER(kind=4)}
2230 @code{K} - @code{INTEGER(kind=8)}
2233 GNU Fortran supports these with the flag @option{-fdec-intrinsic-ints}.
2234 Intrinsics for which prefixed versions are available and in what form are noted
2235 in @ref{Intrinsic Procedures}. The complete list of supported intrinsics is
2238 @multitable @columnfractions .2 .2 .2 .2 .2
2240 @headitem Intrinsic @tab B @tab I @tab J @tab K
2242 @item @code{@ref{ABS}}
2243 @tab @code{BABS} @tab @code{IIABS} @tab @code{JIABS} @tab @code{KIABS}
2244 @item @code{@ref{BTEST}}
2245 @tab @code{BBTEST} @tab @code{BITEST} @tab @code{BJTEST} @tab @code{BKTEST}
2246 @item @code{@ref{IAND}}
2247 @tab @code{BIAND} @tab @code{IIAND} @tab @code{JIAND} @tab @code{KIAND}
2248 @item @code{@ref{IBCLR}}
2249 @tab @code{BBCLR} @tab @code{IIBCLR} @tab @code{JIBCLR} @tab @code{KIBCLR}
2250 @item @code{@ref{IBITS}}
2251 @tab @code{BBITS} @tab @code{IIBITS} @tab @code{JIBITS} @tab @code{KIBITS}
2252 @item @code{@ref{IBSET}}
2253 @tab @code{BBSET} @tab @code{IIBSET} @tab @code{JIBSET} @tab @code{KIBSET}
2254 @item @code{@ref{IEOR}}
2255 @tab @code{BIEOR} @tab @code{IIEOR} @tab @code{JIEOR} @tab @code{KIEOR}
2256 @item @code{@ref{IOR}}
2257 @tab @code{BIOR} @tab @code{IIOR} @tab @code{JIOR} @tab @code{KIOR}
2258 @item @code{@ref{ISHFT}}
2259 @tab @code{BSHFT} @tab @code{IISHFT} @tab @code{JISHFT} @tab @code{KISHFT}
2260 @item @code{@ref{ISHFTC}}
2261 @tab @code{BSHFTC} @tab @code{IISHFTC} @tab @code{JISHFTC} @tab @code{KISHFTC}
2262 @item @code{@ref{MOD}}
2263 @tab @code{BMOD} @tab @code{IMOD} @tab @code{JMOD} @tab @code{KMOD}
2264 @item @code{@ref{NOT}}
2265 @tab @code{BNOT} @tab @code{INOT} @tab @code{JNOT} @tab @code{KNOT}
2266 @item @code{@ref{REAL}}
2267 @tab @code{--} @tab @code{FLOATI} @tab @code{FLOATJ} @tab @code{FLOATK}
2270 @node AUTOMATIC and STATIC attributes
2271 @subsection @code{AUTOMATIC} and @code{STATIC} attributes
2272 @cindex variable attributes
2273 @cindex @code{AUTOMATIC}
2274 @cindex @code{STATIC}
2276 With @option{-fdec-static} GNU Fortran supports the DEC extended attributes
2277 @code{STATIC} and @code{AUTOMATIC} to provide explicit specification of entity
2278 storage. These follow the syntax of the Fortran standard @code{SAVE} attribute.
2280 @code{STATIC} is exactly equivalent to @code{SAVE}, and specifies that
2281 an entity should be allocated in static memory. As an example, @code{STATIC}
2282 local variables will retain their values across multiple calls to a function.
2284 Entities marked @code{AUTOMATIC} will be stack automatic whenever possible.
2285 @code{AUTOMATIC} is the default for local variables smaller than
2286 @option{-fmax-stack-var-size}, unless @option{-fno-automatic} is given. This
2287 attribute overrides @option{-fno-automatic}, @option{-fmax-stack-var-size}, and
2288 blanket @code{SAVE} statements.
2295 integer, automatic :: i ! automatic variable
2296 integer x, y ! static variables
2303 integer a, b, c, x, y, z
2307 ! a, b, c, and z are automatic
2308 ! x and y are static
2312 ! Compiled with -fno-automatic
2316 ! a is automatic; b, c, and d are static
2320 @node Extended math intrinsics
2321 @subsection Extended math intrinsics
2322 @cindex intrinsics, math
2323 @cindex intrinsics, trigonometric functions
2325 GNU Fortran supports an extended list of mathematical intrinsics with the
2326 compile flag @option{-fdec-math} for compatability with legacy code.
2327 These intrinsics are described fully in @ref{Intrinsic Procedures} where it is
2328 noted that they are extensions and should be avoided whenever possible.
2330 Specifically, @option{-fdec-math} enables the @ref{COTAN} intrinsic, and
2331 trigonometric intrinsics which accept or produce values in degrees instead of
2332 radians. Here is a summary of the new intrinsics:
2334 @multitable @columnfractions .5 .5
2335 @headitem Radians @tab Degrees
2336 @item @code{@ref{ACOS}} @tab @code{@ref{ACOSD}}*
2337 @item @code{@ref{ASIN}} @tab @code{@ref{ASIND}}*
2338 @item @code{@ref{ATAN}} @tab @code{@ref{ATAND}}*
2339 @item @code{@ref{ATAN2}} @tab @code{@ref{ATAN2D}}*
2340 @item @code{@ref{COS}} @tab @code{@ref{COSD}}*
2341 @item @code{@ref{COTAN}}* @tab @code{@ref{COTAND}}*
2342 @item @code{@ref{SIN}} @tab @code{@ref{SIND}}*
2343 @item @code{@ref{TAN}} @tab @code{@ref{TAND}}*
2346 * Enabled with @option{-fdec-math}.
2348 For advanced users, it may be important to know the implementation of these
2349 functions. They are simply wrappers around the standard radian functions, which
2350 have more accurate builtin versions. These functions convert their arguments
2351 (or results) to degrees (or radians) by taking the value modulus 360 (or 2*pi)
2352 and then multiplying it by a constant radian-to-degree (or degree-to-radian)
2353 factor, as appropriate. The factor is computed at compile-time as 180/pi (or
2356 @node Form feed as whitespace
2357 @subsection Form feed as whitespace
2358 @cindex form feed whitespace
2360 Historically, legacy compilers allowed insertion of form feed characters ('\f',
2361 ASCII 0xC) at the beginning of lines for formatted output to line printers,
2362 though the Fortran standard does not mention this. GNU Fortran supports the
2363 interpretation of form feed characters in source as whitespace for
2366 @node TYPE as an alias for PRINT
2367 @subsection TYPE as an alias for PRINT
2368 @cindex type alias print
2369 For compatibility, GNU Fortran will interpret @code{TYPE} statements as
2370 @code{PRINT} statements with the flag @option{-fdec}. With this flag asserted,
2371 the following two examples are equivalent:
2374 TYPE *, 'hello world'
2378 PRINT *, 'hello world'
2381 @node %LOC as an rvalue
2382 @subsection %LOC as an rvalue
2384 Normally @code{%LOC} is allowed only in parameter lists. However the intrinsic
2385 function @code{LOC} does the same thing, and is usable as the right-hand-side of
2386 assignments. For compatibility, GNU Fortran supports the use of @code{%LOC} as
2387 an alias for the builtin @code{LOC} with @option{-std=legacy}. With this
2388 feature enabled the following two examples are equivalent:
2401 @node .XOR. operator
2402 @subsection .XOR. operator
2403 @cindex operators, xor
2405 GNU Fortran supports @code{.XOR.} as a logical operator with @code{-std=legacy}
2406 for compatibility with legacy code. @code{.XOR.} is equivalent to
2407 @code{.NEQV.}. That is, the output is true if and only if the inputs differ.
2409 @node Bitwise logical operators
2410 @subsection Bitwise logical operators
2411 @cindex logical, bitwise
2413 With @option{-fdec}, GNU Fortran relaxes the type constraints on
2414 logical operators to allow integer operands, and performs the corresponding
2415 bitwise operation instead. This flag is for compatibility only, and should be
2416 avoided in new code. Consider:
2425 In this example, compiled with @option{-fdec}, GNU Fortran will
2426 replace the @code{.AND.} operation with a call to the intrinsic
2427 @code{@ref{IAND}} function, yielding the bitwise-and of @code{i} and @code{j}.
2429 Note that this conversion will occur if at least one operand is of integral
2430 type. As a result, a logical operand will be converted to an integer when the
2431 other operand is an integer in a logical operation. In this case,
2432 @code{.TRUE.} is converted to @code{1} and @code{.FALSE.} to @code{0}.
2434 Here is the mapping of logical operator to bitwise intrinsic used with
2437 @multitable @columnfractions .25 .25 .5
2438 @headitem Operator @tab Intrinsic @tab Bitwise operation
2439 @item @code{.NOT.} @tab @code{@ref{NOT}} @tab complement
2440 @item @code{.AND.} @tab @code{@ref{IAND}} @tab intersection
2441 @item @code{.OR.} @tab @code{@ref{IOR}} @tab union
2442 @item @code{.NEQV.} @tab @code{@ref{IEOR}} @tab exclusive or
2443 @item @code{.EQV.} @tab @code{@ref{NOT}(@ref{IEOR})} @tab complement of exclusive or
2446 @node Extended I/O specifiers
2447 @subsection Extended I/O specifiers
2448 @cindex @code{CARRIAGECONTROL}
2449 @cindex @code{READONLY}
2450 @cindex @code{SHARE}
2451 @cindex @code{SHARED}
2452 @cindex @code{NOSHARED}
2453 @cindex I/O specifiers
2455 GNU Fortran supports the additional legacy I/O specifiers
2456 @code{CARRIAGECONTROL}, @code{READONLY}, and @code{SHARE} with the
2457 compile flag @option{-fdec}, for compatibility.
2460 @item CARRIAGECONTROL
2461 The @code{CARRIAGECONTROL} specifier allows a user to control line
2462 termination settings between output records for an I/O unit. The specifier has
2463 no meaning for readonly files. When @code{CARRAIGECONTROL} is specified upon
2464 opening a unit for formatted writing, the exact @code{CARRIAGECONTROL} setting
2465 determines what characters to write between output records. The syntax is:
2468 OPEN(..., CARRIAGECONTROL=cc)
2471 Where @emph{cc} is a character expression that evaluates to one of the
2474 @multitable @columnfractions .2 .8
2475 @item @code{'LIST'} @tab One line feed between records (default)
2476 @item @code{'FORTRAN'} @tab Legacy interpretation of the first character (see below)
2477 @item @code{'NONE'} @tab No separator between records
2480 With @code{CARRIAGECONTROL='FORTRAN'}, when a record is written, the first
2481 character of the input record is not written, and instead determines the output
2482 record separator as follows:
2484 @multitable @columnfractions .3 .3 .4
2485 @headitem Leading character @tab Meaning @tab Output separating character(s)
2486 @item @code{'+'} @tab Overprinting @tab Carriage return only
2487 @item @code{'-'} @tab New line @tab Line feed and carriage return
2488 @item @code{'0'} @tab Skip line @tab Two line feeds and carriage return
2489 @item @code{'1'} @tab New page @tab Form feed and carriage return
2490 @item @code{'$'} @tab Prompting @tab Line feed (no carriage return)
2491 @item @code{CHAR(0)} @tab Overprinting (no advance) @tab None
2495 The @code{READONLY} specifier may be given upon opening a unit, and is
2496 equivalent to specifying @code{ACTION='READ'}, except that the file may not be
2497 deleted on close (i.e. @code{CLOSE} with @code{STATUS="DELETE"}). The syntax
2501 @code{OPEN(..., READONLY)}
2505 The @code{SHARE} specifier allows system-level locking on a unit upon opening
2506 it for controlled access from multiple processes/threads. The @code{SHARE}
2507 specifier has several forms:
2515 Where @emph{sh} in the first form is a character expression that evaluates to
2516 a value as seen in the table below. The latter two forms are aliases
2517 for particular values of @emph{sh}:
2519 @multitable @columnfractions .3 .3 .4
2520 @headitem Explicit form @tab Short form @tab Meaning
2521 @item @code{SHARE='DENYRW'} @tab @code{NOSHARED} @tab Exclusive (write) lock
2522 @item @code{SHARE='DENYNONE'} @tab @code{SHARED} @tab Shared (read) lock
2525 In general only one process may hold an exclusive (write) lock for a given file
2526 at a time, whereas many processes may hold shared (read) locks for the same
2529 The behavior of locking may vary with your operating system. On POSIX systems,
2530 locking is implemented with @code{fcntl}. Consult your corresponding operating
2531 system's manual pages for further details. Locking via @code{SHARE=} is not
2532 supported on other systems.
2536 @node Legacy PARAMETER statements
2537 @subsection Legacy PARAMETER statements
2540 For compatibility, GNU Fortran supports legacy PARAMETER statements without
2541 parentheses with @option{-std=legacy}. A warning is emitted if used with
2542 @option{-std=gnu}, and an error is acknowledged with a real Fortran standard
2543 flag (@option{-std=f95}, etc...). These statements take the following form:
2547 parameter e = 2.718282
2552 @node Default exponents
2553 @subsection Default exponents
2556 For compatibility, GNU Fortran supports a default exponent of zero in real
2557 constants with @option{-fdec}. For example, @code{9e} would be
2558 interpreted as @code{9e0}, rather than an error.
2561 @node Extensions not implemented in GNU Fortran
2562 @section Extensions not implemented in GNU Fortran
2563 @cindex extensions, not implemented
2565 The long history of the Fortran language, its wide use and broad
2566 userbase, the large number of different compiler vendors and the lack of
2567 some features crucial to users in the first standards have lead to the
2568 existence of a number of important extensions to the language. While
2569 some of the most useful or popular extensions are supported by the GNU
2570 Fortran compiler, not all existing extensions are supported. This section
2571 aims at listing these extensions and offering advice on how best make
2572 code that uses them running with the GNU Fortran compiler.
2574 @c More can be found here:
2575 @c -- https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html
2576 @c -- the list of Fortran and libgfortran bugs closed as WONTFIX:
2577 @c http://tinyurl.com/2u4h5y
2580 * ENCODE and DECODE statements::
2581 * Variable FORMAT expressions::
2582 @c * TYPE and ACCEPT I/O Statements::
2583 @c * DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers::
2584 @c * Omitted arguments in procedure call::
2585 * Alternate complex function syntax::
2586 * Volatile COMMON blocks::
2587 * OPEN( ... NAME=)::
2588 * Q edit descriptor::
2591 @node ENCODE and DECODE statements
2592 @subsection @code{ENCODE} and @code{DECODE} statements
2593 @cindex @code{ENCODE}
2594 @cindex @code{DECODE}
2596 GNU Fortran does not support the @code{ENCODE} and @code{DECODE}
2597 statements. These statements are best replaced by @code{READ} and
2598 @code{WRITE} statements involving internal files (@code{CHARACTER}
2599 variables and arrays), which have been part of the Fortran standard since
2600 Fortran 77. For example, replace a code fragment like
2605 c ... Code that sets LINE
2606 DECODE (80, 9000, LINE) A, B, C
2607 9000 FORMAT (1X, 3(F10.5))
2614 CHARACTER(LEN=80) LINE
2616 c ... Code that sets LINE
2617 READ (UNIT=LINE, FMT=9000) A, B, C
2618 9000 FORMAT (1X, 3(F10.5))
2621 Similarly, replace a code fragment like
2626 c ... Code that sets A, B and C
2627 ENCODE (80, 9000, LINE) A, B, C
2628 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2635 CHARACTER(LEN=80) LINE
2637 c ... Code that sets A, B and C
2638 WRITE (UNIT=LINE, FMT=9000) A, B, C
2639 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2643 @node Variable FORMAT expressions
2644 @subsection Variable @code{FORMAT} expressions
2645 @cindex @code{FORMAT}
2647 A variable @code{FORMAT} expression is format statement which includes
2648 angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU
2649 Fortran does not support this legacy extension. The effect of variable
2650 format expressions can be reproduced by using the more powerful (and
2651 standard) combination of internal output and string formats. For example,
2652 replace a code fragment like this:
2663 c Variable declaration
2664 CHARACTER(LEN=20) FMT
2666 c Other code here...
2668 WRITE(FMT,'("(I", I0, ")")') N+1
2676 c Variable declaration
2677 CHARACTER(LEN=20) FMT
2679 c Other code here...
2682 WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1
2686 @node Alternate complex function syntax
2687 @subsection Alternate complex function syntax
2688 @cindex Complex function
2690 Some Fortran compilers, including @command{g77}, let the user declare
2691 complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as
2692 well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy
2693 extensions. @command{gfortran} accepts the latter form, which is more
2694 common, but not the former.
2697 @node Volatile COMMON blocks
2698 @subsection Volatile @code{COMMON} blocks
2699 @cindex @code{VOLATILE}
2700 @cindex @code{COMMON}
2702 Some Fortran compilers, including @command{g77}, let the user declare
2703 @code{COMMON} with the @code{VOLATILE} attribute. This is
2704 invalid standard Fortran syntax and is not supported by
2705 @command{gfortran}. Note that @command{gfortran} accepts
2706 @code{VOLATILE} variables in @code{COMMON} blocks since revision 4.3.
2709 @node OPEN( ... NAME=)
2710 @subsection @code{OPEN( ... NAME=)}
2713 Some Fortran compilers, including @command{g77}, let the user declare
2714 @code{OPEN( ... NAME=)}. This is
2715 invalid standard Fortran syntax and is not supported by
2716 @command{gfortran}. @code{OPEN( ... NAME=)} should be replaced
2717 with @code{OPEN( ... FILE=)}.
2719 @node Q edit descriptor
2720 @subsection @code{Q} edit descriptor
2721 @cindex @code{Q} edit descriptor
2723 Some Fortran compilers provide the @code{Q} edit descriptor, which
2724 transfers the number of characters left within an input record into an
2727 A direct replacement of the @code{Q} edit descriptor is not available
2728 in @command{gfortran}. How to replicate its functionality using
2729 standard-conforming code depends on what the intent of the original
2732 Options to replace @code{Q} may be to read the whole line into a
2733 character variable and then counting the number of non-blank
2734 characters left using @code{LEN_TRIM}. Another method may be to use
2735 formatted stream, read the data up to the position where the @code{Q}
2736 descriptor occurred, use @code{INQUIRE} to get the file position,
2737 count the characters up to the next @code{NEW_LINE} and then start
2738 reading from the position marked previously.
2741 @c ---------------------------------------------------------------------
2742 @c ---------------------------------------------------------------------
2743 @c Mixed-Language Programming
2744 @c ---------------------------------------------------------------------
2746 @node Mixed-Language Programming
2747 @chapter Mixed-Language Programming
2748 @cindex Interoperability
2749 @cindex Mixed-language programming
2752 * Interoperability with C::
2753 * GNU Fortran Compiler Directives::
2754 * Non-Fortran Main Program::
2755 * Naming and argument-passing conventions::
2758 This chapter is about mixed-language interoperability, but also
2759 applies if you link Fortran code compiled by different compilers. In
2760 most cases, use of the C Binding features of the Fortran 2003 and
2761 later standards is sufficient.
2763 For example, it is possible to mix Fortran code with C++ code as well
2764 as C, if you declare the interface functions as @code{extern "C"} on
2765 the C++ side and @code{BIND(C)} on the Fortran side, and follow the
2766 rules for interoperability with C. Note that you cannot manipulate
2767 C++ class objects in Fortran or vice versa except as opaque pointers.
2769 You can use the @command{gfortran} command to link both Fortran and
2770 non-Fortran code into the same program, or you can use @command{gcc}
2771 or @command{g++} if you also add an explicit @option{-lgfortran} option
2772 to link with the Fortran library. If your main program is written in
2773 C or some other language instead of Fortran, see
2774 @ref{Non-Fortran Main Program}, below.
2776 @node Interoperability with C
2777 @section Interoperability with C
2778 @cindex interoperability with C
2779 @cindex C interoperability
2783 * Derived Types and struct::
2784 * Interoperable Global Variables::
2785 * Interoperable Subroutines and Functions::
2786 * Working with C Pointers::
2787 * Further Interoperability of Fortran with C::
2790 Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a
2791 standardized way to generate procedure and derived-type
2792 declarations and global variables that are interoperable with C
2793 (ISO/IEC 9899:1999). The @code{BIND(C)} attribute has been added
2794 to inform the compiler that a symbol shall be interoperable with C;
2795 also, some constraints are added. Note, however, that not
2796 all C features have a Fortran equivalent or vice versa. For instance,
2797 neither C's unsigned integers nor C's functions with variable number
2798 of arguments have an equivalent in Fortran.
2800 Note that array dimensions are reversely ordered in C and that arrays in
2801 C always start with index 0 while in Fortran they start by default with
2802 1. Thus, an array declaration @code{A(n,m)} in Fortran matches
2803 @code{A[m][n]} in C and accessing the element @code{A(i,j)} matches
2804 @code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]};
2805 assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}).
2807 @node Intrinsic Types
2808 @subsection Intrinsic Types
2809 @cindex C intrinsic type interoperability
2810 @cindex intrinsic type interoperability with C
2811 @cindex interoperability, intrinsic type
2813 In order to ensure that exactly the same variable type and kind is used
2814 in C and Fortran, you should use the named constants for kind parameters
2815 that are defined in the @code{ISO_C_BINDING} intrinsic module.
2816 That module contains named constants of character type representing
2817 the escaped special characters in C, such as newline.
2818 For a list of the constants, see @ref{ISO_C_BINDING}.
2820 For logical types, please note that the Fortran standard only guarantees
2821 interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
2822 logicals and C99 defines that @code{true} has the value 1 and @code{false}
2823 the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL}
2824 (with any kind parameter) gives an undefined result. (Passing other integer
2825 values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the
2826 integer is explicitly or implicitly casted to @code{_Bool}.)
2828 @node Derived Types and struct
2829 @subsection Derived Types and struct
2830 @cindex C derived type and struct interoperability
2831 @cindex derived type interoperability with C
2832 @cindex interoperability, derived type and struct
2834 For compatibility of derived types with @code{struct}, use
2835 the @code{BIND(C)} attribute in the type declaration. For instance, the
2836 following type declaration
2840 TYPE, BIND(C) :: myType
2841 INTEGER(C_INT) :: i1, i2
2842 INTEGER(C_SIGNED_CHAR) :: i3
2843 REAL(C_DOUBLE) :: d1
2844 COMPLEX(C_FLOAT_COMPLEX) :: c1
2845 CHARACTER(KIND=C_CHAR) :: str(5)
2850 matches the following @code{struct} declaration in C
2855 /* Note: "char" might be signed or unsigned. */
2863 Derived types with the C binding attribute shall not have the @code{sequence}
2864 attribute, type parameters, the @code{extends} attribute, nor type-bound
2865 procedures. Every component must be of interoperable type and kind and may not
2866 have the @code{pointer} or @code{allocatable} attribute. The names of the
2867 components are irrelevant for interoperability.
2869 As there exist no direct Fortran equivalents, neither unions nor structs
2870 with bit field or variable-length array members are interoperable.
2872 @node Interoperable Global Variables
2873 @subsection Interoperable Global Variables
2874 @cindex C variable interoperability
2875 @cindex variable interoperability with C
2876 @cindex interoperability, variable
2878 Variables can be made accessible from C using the C binding attribute,
2879 optionally together with specifying a binding name. Those variables
2880 have to be declared in the declaration part of a @code{MODULE},
2881 be of interoperable type, and have neither the @code{pointer} nor
2882 the @code{allocatable} attribute.
2888 integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag
2889 type(myType), bind(C) :: tp
2893 Here, @code{_MyProject_flags} is the case-sensitive name of the variable
2894 as seen from C programs while @code{global_flag} is the case-insensitive
2895 name as seen from Fortran. If no binding name is specified, as for
2896 @var{tp}, the C binding name is the (lowercase) Fortran binding name.
2897 If a binding name is specified, only a single variable may be after the
2898 double colon. Note of warning: You cannot use a global variable to
2899 access @var{errno} of the C library as the C standard allows it to be
2900 a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead.
2902 @node Interoperable Subroutines and Functions
2903 @subsection Interoperable Subroutines and Functions
2904 @cindex C procedure interoperability
2905 @cindex procedure interoperability with C
2906 @cindex function interoperability with C
2907 @cindex subroutine interoperability with C
2908 @cindex interoperability, subroutine and function
2910 Subroutines and functions have to have the @code{BIND(C)} attribute to
2911 be compatible with C. The dummy argument declaration is relatively
2912 straightforward. However, one needs to be careful because C uses
2913 call-by-value by default while Fortran behaves usually similar to
2914 call-by-reference. Furthermore, strings and pointers are handled
2917 To pass a variable by value, use the @code{VALUE} attribute.
2918 Thus, the following C prototype
2921 @code{int func(int i, int *j)}
2925 matches the Fortran declaration
2928 integer(c_int) function func(i,j)
2929 use iso_c_binding, only: c_int
2930 integer(c_int), VALUE :: i
2934 Note that pointer arguments also frequently need the @code{VALUE} attribute,
2935 see @ref{Working with C Pointers}.
2937 Strings are handled quite differently in C and Fortran. In C a string
2938 is a @code{NUL}-terminated array of characters while in Fortran each string
2939 has a length associated with it and is thus not terminated (by e.g.
2940 @code{NUL}). For example, if you want to use the following C function,
2944 void print_C(char *string) /* equivalent: char string[] */
2946 printf("%s\n", string);
2951 to print ``Hello World'' from Fortran, you can call it using
2954 use iso_c_binding, only: C_CHAR, C_NULL_CHAR
2956 subroutine print_c(string) bind(C, name="print_C")
2957 use iso_c_binding, only: c_char
2958 character(kind=c_char) :: string(*)
2959 end subroutine print_c
2961 call print_c(C_CHAR_"Hello World"//C_NULL_CHAR)
2964 As the example shows, you need to ensure that the
2965 string is @code{NUL} terminated. Additionally, the dummy argument
2966 @var{string} of @code{print_C} is a length-one assumed-size
2967 array; using @code{character(len=*)} is not allowed. The example
2968 above uses @code{c_char_"Hello World"} to ensure the string
2969 literal has the right type; typically the default character
2970 kind and @code{c_char} are the same and thus @code{"Hello World"}
2971 is equivalent. However, the standard does not guarantee this.
2973 The use of strings is now further illustrated using the C library
2974 function @code{strncpy}, whose prototype is
2977 char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
2981 The function @code{strncpy} copies at most @var{n} characters from
2982 string @var{s2} to @var{s1} and returns @var{s1}. In the following
2983 example, we ignore the return value:
2988 character(len=30) :: str,str2
2990 ! Ignore the return value of strncpy -> subroutine
2991 ! "restrict" is always assumed if we do not pass a pointer
2992 subroutine strncpy(dest, src, n) bind(C)
2994 character(kind=c_char), intent(out) :: dest(*)
2995 character(kind=c_char), intent(in) :: src(*)
2996 integer(c_size_t), value, intent(in) :: n
2997 end subroutine strncpy
2999 str = repeat('X',30) ! Initialize whole string with 'X'
3000 call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, &
3001 len(c_char_"Hello World",kind=c_size_t))
3002 print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX"
3006 The intrinsic procedures are described in @ref{Intrinsic Procedures}.
3008 @node Working with C Pointers
3009 @subsection Working with C Pointers
3013 C pointers are represented in Fortran via the special opaque derived
3014 type @code{type(c_ptr)} (with private components). C pointers are distinct
3015 from Fortran objects with the @code{POINTER} attribute. Thus one needs to
3016 use intrinsic conversion procedures to convert from or to C pointers.
3017 For some applications, using an assumed type (@code{TYPE(*)}) can be
3018 an alternative to a C pointer, and you can also use library routines
3019 to access Fortran pointers from C. See @ref{Further Interoperability
3022 Here is an example of using C pointers in Fortran:
3026 type(c_ptr) :: cptr1, cptr2
3027 integer, target :: array(7), scalar
3028 integer, pointer :: pa(:), ps
3029 cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the
3030 ! array is contiguous if required by the C
3032 cptr2 = c_loc(scalar)
3033 call c_f_pointer(cptr2, ps)
3034 call c_f_pointer(cptr2, pa, shape=[7])
3037 When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument
3040 If a pointer is a dummy argument of an interoperable procedure, it usually
3041 has to be declared using the @code{VALUE} attribute. @code{void*}
3042 matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone
3043 matches @code{void**}.
3045 Procedure pointers are handled analogously to pointers; the C type is
3046 @code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are
3047 @code{C_F_PROCPOINTER} and @code{C_FUNLOC}.
3049 Let us consider two examples of actually passing a procedure pointer from
3050 C to Fortran and vice versa. Note that these examples are also very
3051 similar to passing ordinary pointers between both languages. First,
3052 consider this code in C:
3055 /* Procedure implemented in Fortran. */
3056 void get_values (void (*)(double));
3058 /* Call-back routine we want called from Fortran. */
3062 printf ("Number is %f.\n", x);
3065 /* Call Fortran routine and pass call-back to it. */
3069 get_values (&print_it);
3073 A matching implementation for @code{get_values} in Fortran, that correctly
3074 receives the procedure pointer from C and is able to call it, is given
3075 in the following @code{MODULE}:
3081 ! Define interface of call-back routine.
3083 SUBROUTINE callback (x)
3084 USE, INTRINSIC :: ISO_C_BINDING
3085 REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x
3086 END SUBROUTINE callback
3091 ! Define C-bound procedure.
3092 SUBROUTINE get_values (cproc) BIND(C)
3093 USE, INTRINSIC :: ISO_C_BINDING
3094 TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc
3096 PROCEDURE(callback), POINTER :: proc
3098 ! Convert C to Fortran procedure pointer.
3099 CALL C_F_PROCPOINTER (cproc, proc)
3102 CALL proc (1.0_C_DOUBLE)
3103 CALL proc (-42.0_C_DOUBLE)
3104 CALL proc (18.12_C_DOUBLE)
3105 END SUBROUTINE get_values
3110 Next, we want to call a C routine that expects a procedure pointer argument
3111 and pass it a Fortran procedure (which clearly must be interoperable!).
3112 Again, the C function may be:
3116 call_it (int (*func)(int), int arg)
3122 It can be used as in the following Fortran code:
3126 USE, INTRINSIC :: ISO_C_BINDING
3129 ! Define interface of C function.
3131 INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C)
3132 USE, INTRINSIC :: ISO_C_BINDING
3133 TYPE(C_FUNPTR), INTENT(IN), VALUE :: func
3134 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
3135 END FUNCTION call_it
3140 ! Define procedure passed to C function.
3141 ! It must be interoperable!
3142 INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C)
3143 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
3144 double_it = arg + arg
3145 END FUNCTION double_it
3148 SUBROUTINE foobar ()
3149 TYPE(C_FUNPTR) :: cproc
3150 INTEGER(KIND=C_INT) :: i
3152 ! Get C procedure pointer.
3153 cproc = C_FUNLOC (double_it)
3156 DO i = 1_C_INT, 10_C_INT
3157 PRINT *, call_it (cproc, i)
3159 END SUBROUTINE foobar
3164 @node Further Interoperability of Fortran with C
3165 @subsection Further Interoperability of Fortran with C
3166 @cindex Further Interoperability of Fortran with C
3168 @cindex array descriptor
3170 @cindex assumed-type
3171 @cindex assumed-rank
3173 GNU Fortran implements the Technical Specification ISO/IEC TS
3174 29113:2012, which extends the interoperability support of Fortran 2003
3175 and Fortran 2008 and is now part of the 2018 Fortran standard.
3176 Besides removing some restrictions and constraints, the Technical
3177 Specification adds assumed-type (@code{TYPE(*)}) and assumed-rank
3178 (@code{DIMENSION(..)}) variables and allows for interoperability of
3179 assumed-shape, assumed-rank, and deferred-shape arrays, as well as
3180 allocatables and pointers. Objects of these types are passed to
3181 @code{BIND(C)} functions as descriptors with a standard interface,
3182 declared in the header file @code{<ISO_Fortran_binding.h>}.
3184 Note: Currently, GNU Fortran does not use internally the array descriptor
3185 (dope vector) as specified in the Technical Specification, but uses
3186 an array descriptor with different fields in functions without the
3187 @code{BIND(C)} attribute. Arguments to functions marked @code{BIND(C)}
3188 are converted to the specified form. If you need to access GNU Fortran's
3189 internal array descriptor, you can use the Chasm Language Interoperability
3190 Tools, @url{http://chasm-interop.sourceforge.net/}.
3192 @node GNU Fortran Compiler Directives
3193 @section GNU Fortran Compiler Directives
3196 * ATTRIBUTES directive::
3197 * UNROLL directive::
3198 * BUILTIN directive::
3200 * VECTOR directive::
3201 * NOVECTOR directive::
3204 @node ATTRIBUTES directive
3205 @subsection ATTRIBUTES directive
3207 The Fortran standard describes how a conforming program shall
3208 behave; however, the exact implementation is not standardized. In order
3209 to allow the user to choose specific implementation details, compiler
3210 directives can be used to set attributes of variables and procedures
3211 which are not part of the standard. Whether a given attribute is
3212 supported and its exact effects depend on both the operating system and
3213 on the processor; see
3214 @ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)}
3217 For procedures and procedure pointers, the following attributes can
3218 be used to change the calling convention:
3221 @item @code{CDECL} -- standard C calling convention
3222 @item @code{STDCALL} -- convention where the called procedure pops the stack
3223 @item @code{FASTCALL} -- part of the arguments are passed via registers
3224 instead using the stack
3227 Besides changing the calling convention, the attributes also influence
3228 the decoration of the symbol name, e.g., by a leading underscore or by
3229 a trailing at-sign followed by the number of bytes on the stack. When
3230 assigning a procedure to a procedure pointer, both should use the same
3233 On some systems, procedures and global variables (module variables and
3234 @code{COMMON} blocks) need special handling to be accessible when they
3235 are in a shared library. The following attributes are available:
3238 @item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL
3239 @item @code{DLLIMPORT} -- reference the function or variable using a
3243 For dummy arguments, the @code{NO_ARG_CHECK} attribute can be used; in
3244 other compilers, it is also known as @code{IGNORE_TKR}. For dummy arguments
3245 with this attribute actual arguments of any type and kind (similar to
3246 @code{TYPE(*)}), scalars and arrays of any rank (no equivalent
3247 in Fortran standard) are accepted. As with @code{TYPE(*)}, the argument
3248 is unlimited polymorphic and no type information is available.
3249 Additionally, the argument may only be passed to dummy arguments
3250 with the @code{NO_ARG_CHECK} attribute and as argument to the
3251 @code{PRESENT} intrinsic function and to @code{C_LOC} of the
3252 @code{ISO_C_BINDING} module.
3254 Variables with @code{NO_ARG_CHECK} attribute shall be of assumed-type
3255 (@code{TYPE(*)}; recommended) or of type @code{INTEGER}, @code{LOGICAL},
3256 @code{REAL} or @code{COMPLEX}. They shall not have the @code{ALLOCATE},
3257 @code{CODIMENSION}, @code{INTENT(OUT)}, @code{POINTER} or @code{VALUE}
3258 attribute; furthermore, they shall be either scalar or of assumed-size
3259 (@code{dimension(*)}). As @code{TYPE(*)}, the @code{NO_ARG_CHECK} attribute
3260 requires an explicit interface.
3263 @item @code{NO_ARG_CHECK} -- disable the type, kind and rank checking
3264 @item @code{DEPRECATED} -- print a warning when using a such-tagged
3265 deprecated procedure, variable or parameter; the warning can be suppressed
3266 with @option{-Wno-deprecated-declarations}.
3267 @item @code{NOINLINE} -- prevent inlining given function.
3268 @item @code{NORETURN} -- add a hint that a given function cannot return.
3269 @item @code{WEAK} -- emit the declaration of an external symbol as a weak
3270 symbol rather than a global. This is primarily useful in defining library
3271 functions that can be overridden in user code, though it can also be used with
3272 non-function declarations. The overriding symbol must have the same type as
3277 The attributes are specified using the syntax
3279 @code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list}
3281 where in free-form source code only whitespace is allowed before @code{!GCC$}
3282 and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall
3283 start in the first column.
3285 For procedures, the compiler directives shall be placed into the body
3286 of the procedure; for variables and procedure pointers, they shall be in
3287 the same declaration part as the variable or procedure pointer.
3290 @node UNROLL directive
3291 @subsection UNROLL directive
3293 The syntax of the directive is
3295 @code{!GCC$ unroll N}
3297 You can use this directive to control how many times a loop should be unrolled.
3298 It must be placed immediately before a @code{DO} loop and applies only to the
3299 loop that follows. N is an integer constant specifying the unrolling factor.
3300 The values of 0 and 1 block any unrolling of the loop.
3303 @node BUILTIN directive
3304 @subsection BUILTIN directive
3306 The syntax of the directive is
3308 @code{!GCC$ BUILTIN (B) attributes simd FLAGS IF('target')}
3310 You can use this directive to define which middle-end built-ins provide vector
3311 implementations. @code{B} is name of the middle-end built-in. @code{FLAGS}
3312 are optional and must be either "(inbranch)" or "(notinbranch)".
3313 @code{IF} statement is optional and is used to filter multilib ABIs
3314 for the built-in that should be vectorized. Example usage:
3317 !GCC$ builtin (sinf) attributes simd (notinbranch) if('x86_64')
3320 The purpose of the directive is to provide an API among the GCC compiler and
3321 the GNU C Library which would define vector implementations of math routines.
3324 @node IVDEP directive
3325 @subsection IVDEP directive
3327 The syntax of the directive is
3331 This directive tells the compiler to ignore vector dependencies in the
3332 following loop. It must be placed immediately before a @code{DO} loop
3333 and applies only to the loop that follows.
3335 Sometimes the compiler may not have sufficient information to decide
3336 whether a particular loop is vectorizable due to potential
3337 dependencies between iterations. The purpose of the directive is to
3338 tell the compiler that vectorization is safe.
3340 This directive is intended for annotation of existing code. For new
3341 code it is recommended to consider OpenMP SIMD directives as potential
3345 @node VECTOR directive
3346 @subsection VECTOR directive
3348 The syntax of the directive is
3352 This directive tells the compiler to vectorize the following loop. It
3353 must be placed immediately before a @code{DO} loop and applies only to
3354 the loop that follows.
3357 @node NOVECTOR directive
3358 @subsection NOVECTOR directive
3360 The syntax of the directive is
3362 @code{!GCC$ novector}
3364 This directive tells the compiler to not vectorize the following loop.
3365 It must be placed immediately before a @code{DO} loop and applies only
3366 to the loop that follows.
3369 @node Non-Fortran Main Program
3370 @section Non-Fortran Main Program
3373 * _gfortran_set_args:: Save command-line arguments
3374 * _gfortran_set_options:: Set library option flags
3375 * _gfortran_set_convert:: Set endian conversion
3376 * _gfortran_set_record_marker:: Set length of record markers
3377 * _gfortran_set_fpe:: Set when a Floating Point Exception should be raised
3378 * _gfortran_set_max_subrecord_length:: Set subrecord length
3381 Even if you are doing mixed-language programming, it is very
3382 likely that you do not need to know or use the information in this
3383 section. Since it is about the internal structure of GNU Fortran,
3384 it may also change in GCC minor releases.
3386 When you compile a @code{PROGRAM} with GNU Fortran, a function
3387 with the name @code{main} (in the symbol table of the object file)
3388 is generated, which initializes the libgfortran library and then
3389 calls the actual program which uses the name @code{MAIN__}, for
3390 historic reasons. If you link GNU Fortran compiled procedures
3391 to, e.g., a C or C++ program or to a Fortran program compiled by
3392 a different compiler, the libgfortran library is not initialized
3393 and thus a few intrinsic procedures do not work properly, e.g.
3394 those for obtaining the command-line arguments.
3396 Therefore, if your @code{PROGRAM} is not compiled with
3397 GNU Fortran and the GNU Fortran compiled procedures require
3398 intrinsics relying on the library initialization, you need to
3399 initialize the library yourself. Using the default options,
3400 gfortran calls @code{_gfortran_set_args} and
3401 @code{_gfortran_set_options}. The initialization of the former
3402 is needed if the called procedures access the command line
3403 (and for backtracing); the latter sets some flags based on the
3404 standard chosen or to enable backtracing. In typical programs,
3405 it is not necessary to call any initialization function.
3407 If your @code{PROGRAM} is compiled with GNU Fortran, you shall
3408 not call any of the following functions. The libgfortran
3409 initialization functions are shown in C syntax but using C
3410 bindings they are also accessible from Fortran.
3413 @node _gfortran_set_args
3414 @subsection @code{_gfortran_set_args} --- Save command-line arguments
3415 @fnindex _gfortran_set_args
3416 @cindex libgfortran initialization, set_args
3419 @item @emph{Description}:
3420 @code{_gfortran_set_args} saves the command-line arguments; this
3421 initialization is required if any of the command-line intrinsics
3422 is called. Additionally, it shall be called if backtracing is
3423 enabled (see @code{_gfortran_set_options}).
3425 @item @emph{Syntax}:
3426 @code{void _gfortran_set_args (int argc, char *argv[])}
3428 @item @emph{Arguments}:
3429 @multitable @columnfractions .15 .70
3430 @item @var{argc} @tab number of command line argument strings
3431 @item @var{argv} @tab the command-line argument strings; argv[0]
3432 is the pathname of the executable itself.
3435 @item @emph{Example}:
3437 int main (int argc, char *argv[])
3439 /* Initialize libgfortran. */
3440 _gfortran_set_args (argc, argv);
3447 @node _gfortran_set_options
3448 @subsection @code{_gfortran_set_options} --- Set library option flags
3449 @fnindex _gfortran_set_options
3450 @cindex libgfortran initialization, set_options
3453 @item @emph{Description}:
3454 @code{_gfortran_set_options} sets several flags related to the Fortran
3455 standard to be used, whether backtracing should be enabled
3456 and whether range checks should be performed. The syntax allows for
3457 upward compatibility since the number of passed flags is specified; for
3458 non-passed flags, the default value is used. See also
3459 @pxref{Code Gen Options}. Please note that not all flags are actually
3462 @item @emph{Syntax}:
3463 @code{void _gfortran_set_options (int num, int options[])}
3465 @item @emph{Arguments}:
3466 @multitable @columnfractions .15 .70
3467 @item @var{num} @tab number of options passed
3468 @item @var{argv} @tab The list of flag values
3471 @item @emph{option flag list}:
3472 @multitable @columnfractions .15 .70
3473 @item @var{option}[0] @tab Allowed standard; can give run-time errors
3474 if e.g. an input-output edit descriptor is invalid in a given
3475 standard. Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1),
3476 @code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4),
3477 @code{GFC_STD_F95} (8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU}
3478 (32), @code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128),
3479 @code{GFC_STD_F2008_OBS} (256), @code{GFC_STD_F2008_TS} (512),
3480 @code{GFC_STD_F2018} (1024), @code{GFC_STD_F2018_OBS} (2048), and
3481 @code{GFC_STD=F2018_DEL} (4096). Default: @code{GFC_STD_F95_OBS |
3482 GFC_STD_F95_DEL | GFC_STD_F95 | GFC_STD_F2003 | GFC_STD_F2008 |
3483 GFC_STD_F2008_TS | GFC_STD_F2008_OBS | GFC_STD_F77 | GFC_STD_F2018 |
3484 GFC_STD_F2018_OBS | GFC_STD_F2018_DEL | GFC_STD_GNU | GFC_STD_LEGACY}.
3485 @item @var{option}[1] @tab Standard-warning flag; prints a warning to
3486 standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}.
3487 @item @var{option}[2] @tab If non zero, enable pedantic checking.
3489 @item @var{option}[3] @tab Unused.
3490 @item @var{option}[4] @tab If non zero, enable backtracing on run-time
3491 errors. Default: off. (Default in the compiler: on.)
3492 Note: Installs a signal handler and requires command-line
3493 initialization using @code{_gfortran_set_args}.
3494 @item @var{option}[5] @tab If non zero, supports signed zeros.
3496 @item @var{option}[6] @tab Enables run-time checking. Possible values
3497 are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2),
3498 GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (8), GFC_RTCHECK_POINTER (16),
3499 GFC_RTCHECK_MEM (32), GFC_RTCHECK_BITS (64).
3501 @item @var{option}[7] @tab Unused.
3502 @item @var{option}[8] @tab Show a warning when invoking @code{STOP} and
3503 @code{ERROR STOP} if a floating-point exception occurred. Possible values
3504 are (bitwise or-ed) @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3505 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3506 @code{GFC_FPE_UNDERFLOW} (16), @code{GFC_FPE_INEXACT} (32). Default: None (0).
3507 (Default in the compiler: @code{GFC_FPE_INVALID | GFC_FPE_DENORMAL |
3508 GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW}.)
3511 @item @emph{Example}:
3513 /* Use gfortran 4.9 default options. */
3514 static int options[] = @{68, 511, 0, 0, 1, 1, 0, 0, 31@};
3515 _gfortran_set_options (9, &options);
3520 @node _gfortran_set_convert
3521 @subsection @code{_gfortran_set_convert} --- Set endian conversion
3522 @fnindex _gfortran_set_convert
3523 @cindex libgfortran initialization, set_convert
3526 @item @emph{Description}:
3527 @code{_gfortran_set_convert} set the representation of data for
3530 @item @emph{Syntax}:
3531 @code{void _gfortran_set_convert (int conv)}
3533 @item @emph{Arguments}:
3534 @multitable @columnfractions .15 .70
3535 @item @var{conv} @tab Endian conversion, possible values:
3536 GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1),
3537 GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3).
3540 @item @emph{Example}:
3542 int main (int argc, char *argv[])
3544 /* Initialize libgfortran. */
3545 _gfortran_set_args (argc, argv);
3546 _gfortran_set_convert (1);
3553 @node _gfortran_set_record_marker
3554 @subsection @code{_gfortran_set_record_marker} --- Set length of record markers
3555 @fnindex _gfortran_set_record_marker
3556 @cindex libgfortran initialization, set_record_marker
3559 @item @emph{Description}:
3560 @code{_gfortran_set_record_marker} sets the length of record markers
3561 for unformatted files.
3563 @item @emph{Syntax}:
3564 @code{void _gfortran_set_record_marker (int val)}
3566 @item @emph{Arguments}:
3567 @multitable @columnfractions .15 .70
3568 @item @var{val} @tab Length of the record marker; valid values
3569 are 4 and 8. Default is 4.
3572 @item @emph{Example}:
3574 int main (int argc, char *argv[])
3576 /* Initialize libgfortran. */
3577 _gfortran_set_args (argc, argv);
3578 _gfortran_set_record_marker (8);
3585 @node _gfortran_set_fpe
3586 @subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps
3587 @fnindex _gfortran_set_fpe
3588 @cindex libgfortran initialization, set_fpe
3591 @item @emph{Description}:
3592 @code{_gfortran_set_fpe} enables floating point exception traps for
3593 the specified exceptions. On most systems, this will result in a
3594 SIGFPE signal being sent and the program being aborted.
3596 @item @emph{Syntax}:
3597 @code{void _gfortran_set_fpe (int val)}
3599 @item @emph{Arguments}:
3600 @multitable @columnfractions .15 .70
3601 @item @var{option}[0] @tab IEEE exceptions. Possible values are
3602 (bitwise or-ed) zero (0, default) no trapping,
3603 @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3604 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3605 @code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32).
3608 @item @emph{Example}:
3610 int main (int argc, char *argv[])
3612 /* Initialize libgfortran. */
3613 _gfortran_set_args (argc, argv);
3614 /* FPE for invalid operations such as SQRT(-1.0). */
3615 _gfortran_set_fpe (1);
3622 @node _gfortran_set_max_subrecord_length
3623 @subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length
3624 @fnindex _gfortran_set_max_subrecord_length
3625 @cindex libgfortran initialization, set_max_subrecord_length
3628 @item @emph{Description}:
3629 @code{_gfortran_set_max_subrecord_length} set the maximum length
3630 for a subrecord. This option only makes sense for testing and
3631 debugging of unformatted I/O.
3633 @item @emph{Syntax}:
3634 @code{void _gfortran_set_max_subrecord_length (int val)}
3636 @item @emph{Arguments}:
3637 @multitable @columnfractions .15 .70
3638 @item @var{val} @tab the maximum length for a subrecord;
3639 the maximum permitted value is 2147483639, which is also
3643 @item @emph{Example}:
3645 int main (int argc, char *argv[])
3647 /* Initialize libgfortran. */
3648 _gfortran_set_args (argc, argv);
3649 _gfortran_set_max_subrecord_length (8);
3656 @node Naming and argument-passing conventions
3657 @section Naming and argument-passing conventions
3659 This section gives an overview about the naming convention of procedures
3660 and global variables and about the argument passing conventions used by
3661 GNU Fortran. If a C binding has been specified, the naming convention
3662 and some of the argument-passing conventions change. If possible,
3663 mixed-language and mixed-compiler projects should use the better defined
3664 C binding for interoperability. See @pxref{Interoperability with C}.
3667 * Naming conventions::
3668 * Argument passing conventions::
3672 @node Naming conventions
3673 @subsection Naming conventions
3675 According the Fortran standard, valid Fortran names consist of a letter
3676 between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0},
3677 @code{1} to @code{9} and underscores (@code{_}) with the restriction
3678 that names may only start with a letter. As vendor extension, the
3679 dollar sign (@code{$}) is additionally permitted with the option
3680 @option{-fdollar-ok}, but not as first character and only if the
3681 target system supports it.
3683 By default, the procedure name is the lower-cased Fortran name with an
3684 appended underscore (@code{_}); using @option{-fno-underscoring} no
3685 underscore is appended while @code{-fsecond-underscore} appends two
3686 underscores. Depending on the target system and the calling convention,
3687 the procedure might be additionally dressed; for instance, on 32bit
3688 Windows with @code{stdcall}, an at-sign @code{@@} followed by an integer
3689 number is appended. For the changing the calling convention, see
3690 @pxref{GNU Fortran Compiler Directives}.
3692 For common blocks, the same convention is used, i.e. by default an
3693 underscore is appended to the lower-cased Fortran name. Blank commons
3694 have the name @code{__BLNK__}.
3696 For procedures and variables declared in the specification space of a
3697 module, the name is formed by @code{__}, followed by the lower-cased
3698 module name, @code{_MOD_}, and the lower-cased Fortran name. Note that
3699 no underscore is appended.
3702 @node Argument passing conventions
3703 @subsection Argument passing conventions
3705 Subroutines do not return a value (matching C99's @code{void}) while
3706 functions either return a value as specified in the platform ABI or
3707 the result variable is passed as hidden argument to the function and
3708 no result is returned. A hidden result variable is used when the
3709 result variable is an array or of type @code{CHARACTER}.
3711 Arguments are passed according to the platform ABI. In particular,
3712 complex arguments might not be compatible to a struct with two real
3713 components for the real and imaginary part. The argument passing
3714 matches the one of C99's @code{_Complex}. Functions with scalar
3715 complex result variables return their value and do not use a
3716 by-reference argument. Note that with the @option{-ff2c} option,
3717 the argument passing is modified and no longer completely matches
3718 the platform ABI. Some other Fortran compilers use @code{f2c}
3719 semantic by default; this might cause problems with
3722 GNU Fortran passes most arguments by reference, i.e. by passing a
3723 pointer to the data. Note that the compiler might use a temporary
3724 variable into which the actual argument has been copied, if required
3725 semantically (copy-in/copy-out).
3727 For arguments with @code{ALLOCATABLE} and @code{POINTER}
3728 attribute (including procedure pointers), a pointer to the pointer
3729 is passed such that the pointer address can be modified in the
3732 For dummy arguments with the @code{VALUE} attribute: Scalar arguments
3733 of the type @code{INTEGER}, @code{LOGICAL}, @code{REAL} and
3734 @code{COMPLEX} are passed by value according to the platform ABI.
3735 (As vendor extension and not recommended, using @code{%VAL()} in the
3736 call to a procedure has the same effect.) For @code{TYPE(C_PTR)} and
3737 procedure pointers, the pointer itself is passed such that it can be
3738 modified without affecting the caller.
3739 @c FIXME: Document how VALUE is handled for CHARACTER, TYPE,
3740 @c CLASS and arrays, i.e. whether the copy-in is done in the caller
3741 @c or in the callee.
3743 For Boolean (@code{LOGICAL}) arguments, please note that GCC expects
3744 only the integer value 0 and 1. If a GNU Fortran @code{LOGICAL}
3745 variable contains another integer value, the result is undefined.
3746 As some other Fortran compilers use @math{-1} for @code{.TRUE.},
3747 extra care has to be taken -- such as passing the value as
3748 @code{INTEGER}. (The same value restriction also applies to other
3749 front ends of GCC, e.g. to GCC's C99 compiler for @code{_Bool}
3750 or GCC's Ada compiler for @code{Boolean}.)
3752 For arguments of @code{CHARACTER} type, the character length is passed
3753 as a hidden argument at the end of the argument list, except when the
3754 corresponding dummy argument is declared as @code{TYPE(*)}. For
3755 deferred-length strings, the value is passed by reference, otherwise
3756 by value. The character length has the C type @code{size_t} (or
3757 @code{INTEGER(kind=C_SIZE_T)} in Fortran). Note that this is
3758 different to older versions of the GNU Fortran compiler, where the
3759 type of the hidden character length argument was a C @code{int}. In
3760 order to retain compatibility with older versions, one can e.g. for
3761 the following Fortran procedure
3764 subroutine fstrlen (s, a)
3765 character(len=*) :: s
3768 end subroutine fstrlen
3771 define the corresponding C prototype as follows:
3775 typedef size_t fortran_charlen_t;
3777 typedef int fortran_charlen_t;
3780 void fstrlen_ (char*, int*, fortran_charlen_t);
3783 In order to avoid such compiler-specific details, for new code it is
3784 instead recommended to use the ISO_C_BINDING feature.
3786 Note with C binding, @code{CHARACTER(len=1)} result variables are
3787 returned according to the platform ABI and no hidden length argument
3788 is used for dummy arguments; with @code{VALUE}, those variables are
3791 For @code{OPTIONAL} dummy arguments, an absent argument is denoted
3792 by a NULL pointer, except for scalar dummy arguments of intrinsic type
3793 which have the @code{VALUE} attribute. For those, a hidden Boolean
3794 argument (@code{logical(kind=C_bool),value}) is used to indicate
3795 whether the argument is present.
3797 Arguments which are assumed-shape, assumed-rank or deferred-rank
3798 arrays or, with @option{-fcoarray=lib}, allocatable scalar coarrays use
3799 an array descriptor. All other arrays pass the address of the
3800 first element of the array. With @option{-fcoarray=lib}, the token
3801 and the offset belonging to nonallocatable coarrays dummy arguments
3802 are passed as hidden argument along the character length hidden
3803 arguments. The token is an opaque pointer identifying the coarray
3804 and the offset is a passed-by-value integer of kind @code{C_PTRDIFF_T},
3805 denoting the byte offset between the base address of the coarray and
3806 the passed scalar or first element of the passed array.
3808 The arguments are passed in the following order
3810 @item Result variable, when the function result is passed by reference
3811 @item Character length of the function result, if it is a of type
3812 @code{CHARACTER} and no C binding is used
3813 @item The arguments in the order in which they appear in the Fortran
3815 @item The present status for optional arguments with value attribute,
3816 which are internally passed by value
3817 @item The character length and/or coarray token and offset for the first
3818 argument which is a @code{CHARACTER} or a nonallocatable coarray dummy
3819 argument, followed by the hidden arguments of the next dummy argument
3824 @c ---------------------------------------------------------------------
3825 @c Coarray Programming
3826 @c ---------------------------------------------------------------------
3828 @node Coarray Programming
3829 @chapter Coarray Programming
3833 * Type and enum ABI Documentation::
3834 * Function ABI Documentation::
3838 @node Type and enum ABI Documentation
3839 @section Type and enum ABI Documentation
3844 * caf_deregister_t::
3850 @subsection @code{caf_token_t}
3852 Typedef of type @code{void *} on the compiler side. Can be any data
3853 type on the library side.
3855 @node caf_register_t
3856 @subsection @code{caf_register_t}
3858 Indicates which kind of coarray variable should be registered.
3861 typedef enum caf_register_t {
3862 CAF_REGTYPE_COARRAY_STATIC,
3863 CAF_REGTYPE_COARRAY_ALLOC,
3864 CAF_REGTYPE_LOCK_STATIC,
3865 CAF_REGTYPE_LOCK_ALLOC,
3866 CAF_REGTYPE_CRITICAL,
3867 CAF_REGTYPE_EVENT_STATIC,
3868 CAF_REGTYPE_EVENT_ALLOC,
3869 CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY,
3870 CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY
3875 The values @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and
3876 @code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} are for allocatable components
3877 in derived type coarrays only. The first one sets up the token without
3878 allocating memory for allocatable component. The latter one only allocates the
3879 memory for an allocatable component in a derived type coarray. The token
3880 needs to be setup previously by the REGISTER_ONLY. This allows to have
3881 allocatable components un-allocated on some images. The status whether an
3882 allocatable component is allocated on a remote image can be queried by
3883 @code{_caf_is_present} which used internally by the @code{ALLOCATED}
3886 @node caf_deregister_t
3887 @subsection @code{caf_deregister_t}
3890 typedef enum caf_deregister_t {
3891 CAF_DEREGTYPE_COARRAY_DEREGISTER,
3892 CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY
3897 Allows to specify the type of deregistration of a coarray object. The
3898 @code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} flag is only allowed for
3899 allocatable components in derived type coarrays.
3901 @node caf_reference_t
3902 @subsection @code{caf_reference_t}
3904 The structure used for implementing arbitrary reference chains.
3905 A @code{CAF_REFERENCE_T} allows to specify a component reference or any kind
3906 of array reference of any rank supported by gfortran. For array references all
3907 kinds as known by the compiler/Fortran standard are supported indicated by
3911 typedef enum caf_ref_type_t {
3912 /* Reference a component of a derived type, either regular one or an
3913 allocatable or pointer type. For regular ones idx in caf_reference_t is
3916 /* Reference an allocatable array. */
3918 /* Reference a non-allocatable/non-pointer array. I.e., the coarray object
3919 has no array descriptor associated and the addressing is done
3920 completely using the ref. */
3921 CAF_REF_STATIC_ARRAY
3926 typedef enum caf_array_ref_t {
3927 /* No array ref. This terminates the array ref. */
3928 CAF_ARR_REF_NONE = 0,
3929 /* Reference array elements given by a vector. Only for this mode
3930 caf_reference_t.u.a.dim[i].v is valid. */
3932 /* A full array ref (:). */
3934 /* Reference a range on elements given by start, end and stride. */
3936 /* Only a single item is referenced given in the start member. */
3938 /* An array ref of the kind (i:), where i is an arbitrary valid index in the
3939 array. The index i is given in the start member. */
3940 CAF_ARR_REF_OPEN_END,
3941 /* An array ref of the kind (:i), where the lower bound of the array ref
3942 is given by the remote side. The index i is given in the end member. */
3943 CAF_ARR_REF_OPEN_START
3948 /* References to remote components of a derived type. */
3949 typedef struct caf_reference_t {
3950 /* A pointer to the next ref or NULL. */
3951 struct caf_reference_t *next;
3952 /* The type of the reference. */
3953 /* caf_ref_type_t, replaced by int to allow specification in fortran FE. */
3955 /* The size of an item referenced in bytes. I.e. in an array ref this is
3956 the factor to advance the array pointer with to get to the next item.
3957 For component refs this gives just the size of the element referenced. */
3961 /* The offset (in bytes) of the component in the derived type.
3962 Unused for allocatable or pointer components. */
3964 /* The offset (in bytes) to the caf_token associated with this
3965 component. NULL, when not allocatable/pointer ref. */
3966 ptrdiff_t caf_token_offset;
3969 /* The mode of the array ref. See CAF_ARR_REF_*. */
3970 /* caf_array_ref_t, replaced by unsigend char to allow specification in
3972 unsigned char mode[GFC_MAX_DIMENSIONS];
3973 /* The type of a static array. Unset for array's with descriptors. */
3974 int static_array_type;
3975 /* Subscript refs (s) or vector refs (v). */
3978 /* The start and end boundary of the ref and the stride. */
3979 index_type start, end, stride;
3982 /* nvec entries of kind giving the elements to reference. */
3984 /* The number of entries in vector. */
3986 /* The integer kind used for the elements in vector. */
3989 } dim[GFC_MAX_DIMENSIONS];
3995 The references make up a single linked list of reference operations. The
3996 @code{NEXT} member links to the next reference or NULL to indicate the end of
3997 the chain. Component and array refs can be arbitrarily mixed as long as they
3998 comply to the Fortran standard.
4001 The member @code{STATIC_ARRAY_TYPE} is used only when the @code{TYPE} is
4002 @code{CAF_REF_STATIC_ARRAY}. The member gives the type of the data referenced.
4003 Because no array descriptor is available for a descriptor-less array and
4004 type conversion still needs to take place the type is transported here.
4006 At the moment @code{CAF_ARR_REF_VECTOR} is not implemented in the front end for
4007 descriptor-less arrays. The library caf_single has untested support for it.
4010 @subsection @code{caf_team_t}
4012 Opaque pointer to represent a team-handle. This type is a stand-in for the
4013 future implementation of teams. It is about to change without further notice.
4015 @node Function ABI Documentation
4016 @section Function ABI Documentation
4019 * _gfortran_caf_init:: Initialiation function
4020 * _gfortran_caf_finish:: Finalization function
4021 * _gfortran_caf_this_image:: Querying the image number
4022 * _gfortran_caf_num_images:: Querying the maximal number of images
4023 * _gfortran_caf_image_status :: Query the status of an image
4024 * _gfortran_caf_failed_images :: Get an array of the indexes of the failed images
4025 * _gfortran_caf_stopped_images :: Get an array of the indexes of the stopped images
4026 * _gfortran_caf_register:: Registering coarrays
4027 * _gfortran_caf_deregister:: Deregistering coarrays
4028 * _gfortran_caf_is_present:: Query whether an allocatable or pointer component in a derived type coarray is allocated
4029 * _gfortran_caf_send:: Sending data from a local image to a remote image
4030 * _gfortran_caf_get:: Getting data from a remote image
4031 * _gfortran_caf_sendget:: Sending data between remote images
4032 * _gfortran_caf_send_by_ref:: Sending data from a local image to a remote image using enhanced references
4033 * _gfortran_caf_get_by_ref:: Getting data from a remote image using enhanced references
4034 * _gfortran_caf_sendget_by_ref:: Sending data between remote images using enhanced references
4035 * _gfortran_caf_lock:: Locking a lock variable
4036 * _gfortran_caf_unlock:: Unlocking a lock variable
4037 * _gfortran_caf_event_post:: Post an event
4038 * _gfortran_caf_event_wait:: Wait that an event occurred
4039 * _gfortran_caf_event_query:: Query event count
4040 * _gfortran_caf_sync_all:: All-image barrier
4041 * _gfortran_caf_sync_images:: Barrier for selected images
4042 * _gfortran_caf_sync_memory:: Wait for completion of segment-memory operations
4043 * _gfortran_caf_error_stop:: Error termination with exit code
4044 * _gfortran_caf_error_stop_str:: Error termination with string
4045 * _gfortran_caf_fail_image :: Mark the image failed and end its execution
4046 * _gfortran_caf_atomic_define:: Atomic variable assignment
4047 * _gfortran_caf_atomic_ref:: Atomic variable reference
4048 * _gfortran_caf_atomic_cas:: Atomic compare and swap
4049 * _gfortran_caf_atomic_op:: Atomic operation
4050 * _gfortran_caf_co_broadcast:: Sending data to all images
4051 * _gfortran_caf_co_max:: Collective maximum reduction
4052 * _gfortran_caf_co_min:: Collective minimum reduction
4053 * _gfortran_caf_co_sum:: Collective summing reduction
4054 * _gfortran_caf_co_reduce:: Generic collective reduction
4058 @node _gfortran_caf_init
4059 @subsection @code{_gfortran_caf_init} --- Initialiation function
4060 @cindex Coarray, _gfortran_caf_init
4063 @item @emph{Description}:
4064 This function is called at startup of the program before the Fortran main
4065 program, if the latter has been compiled with @option{-fcoarray=lib}.
4066 It takes as arguments the command-line arguments of the program. It is
4067 permitted to pass two @code{NULL} pointers as argument; if non-@code{NULL},
4068 the library is permitted to modify the arguments.
4070 @item @emph{Syntax}:
4071 @code{void _gfortran_caf_init (int *argc, char ***argv)}
4073 @item @emph{Arguments}:
4074 @multitable @columnfractions .15 .70
4075 @item @var{argc} @tab intent(inout) An integer pointer with the number of
4076 arguments passed to the program or @code{NULL}.
4077 @item @var{argv} @tab intent(inout) A pointer to an array of strings with the
4078 command-line arguments or @code{NULL}.
4082 The function is modelled after the initialization function of the Message
4083 Passing Interface (MPI) specification. Due to the way coarray registration
4084 works, it might not be the first call to the library. If the main program is
4085 not written in Fortran and only a library uses coarrays, it can happen that
4086 this function is never called. Therefore, it is recommended that the library
4087 does not rely on the passed arguments and whether the call has been done.
4091 @node _gfortran_caf_finish
4092 @subsection @code{_gfortran_caf_finish} --- Finalization function
4093 @cindex Coarray, _gfortran_caf_finish
4096 @item @emph{Description}:
4097 This function is called at the end of the Fortran main program, if it has
4098 been compiled with the @option{-fcoarray=lib} option.
4100 @item @emph{Syntax}:
4101 @code{void _gfortran_caf_finish (void)}
4104 For non-Fortran programs, it is recommended to call the function at the end
4105 of the main program. To ensure that the shutdown is also performed for
4106 programs where this function is not explicitly invoked, for instance
4107 non-Fortran programs or calls to the system's exit() function, the library
4108 can use a destructor function. Note that programs can also be terminated
4109 using the STOP and ERROR STOP statements; those use different library calls.
4113 @node _gfortran_caf_this_image
4114 @subsection @code{_gfortran_caf_this_image} --- Querying the image number
4115 @cindex Coarray, _gfortran_caf_this_image
4118 @item @emph{Description}:
4119 This function returns the current image number, which is a positive number.
4121 @item @emph{Syntax}:
4122 @code{int _gfortran_caf_this_image (int distance)}
4124 @item @emph{Arguments}:
4125 @multitable @columnfractions .15 .70
4126 @item @var{distance} @tab As specified for the @code{this_image} intrinsic
4127 in TS18508. Shall be a non-negative number.
4131 If the Fortran intrinsic @code{this_image} is invoked without an argument, which
4132 is the only permitted form in Fortran 2008, GCC passes @code{0} as
4137 @node _gfortran_caf_num_images
4138 @subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images
4139 @cindex Coarray, _gfortran_caf_num_images
4142 @item @emph{Description}:
4143 This function returns the number of images in the current team, if
4144 @var{distance} is 0 or the number of images in the parent team at the specified
4145 distance. If failed is -1, the function returns the number of all images at
4146 the specified distance; if it is 0, the function returns the number of
4147 nonfailed images, and if it is 1, it returns the number of failed images.
4149 @item @emph{Syntax}:
4150 @code{int _gfortran_caf_num_images(int distance, int failed)}
4152 @item @emph{Arguments}:
4153 @multitable @columnfractions .15 .70
4154 @item @var{distance} @tab the distance from this image to the ancestor.
4156 @item @var{failed} @tab shall be -1, 0, or 1
4160 This function follows TS18508. If the num_image intrinsic has no arguments,
4161 then the compiler passes @code{distance=0} and @code{failed=-1} to the function.
4165 @node _gfortran_caf_image_status
4166 @subsection @code{_gfortran_caf_image_status} --- Query the status of an image
4167 @cindex Coarray, _gfortran_caf_image_status
4170 @item @emph{Description}:
4171 Get the status of the image given by the id @var{image} of the team given by
4172 @var{team}. Valid results are zero, for image is ok, @code{STAT_STOPPED_IMAGE}
4173 from the ISO_FORTRAN_ENV module to indicate that the image has been stopped and
4174 @code{STAT_FAILED_IMAGE} also from ISO_FORTRAN_ENV to indicate that the image
4175 has executed a @code{FAIL IMAGE} statement.
4177 @item @emph{Syntax}:
4178 @code{int _gfortran_caf_image_status (int image, caf_team_t * team)}
4180 @item @emph{Arguments}:
4181 @multitable @columnfractions .15 .70
4182 @item @var{image} @tab the positive scalar id of the image in the current TEAM.
4183 @item @var{team} @tab optional; team on the which the inquiry is to be
4188 This function follows TS18508. Because team-functionality is not yet
4189 implemented a null-pointer is passed for the @var{team} argument at the moment.
4193 @node _gfortran_caf_failed_images
4194 @subsection @code{_gfortran_caf_failed_images} --- Get an array of the indexes of the failed images
4195 @cindex Coarray, _gfortran_caf_failed_images
4198 @item @emph{Description}:
4199 Get an array of image indexes in the current @var{team} that have failed. The
4200 array is sorted ascendingly. When @var{team} is not provided the current team
4201 is to be used. When @var{kind} is provided then the resulting array is of that
4202 integer kind else it is of default integer kind. The returns an unallocated
4203 size zero array when no images have failed.
4205 @item @emph{Syntax}:
4206 @code{int _gfortran_caf_failed_images (caf_team_t * team, int * kind)}
4208 @item @emph{Arguments}:
4209 @multitable @columnfractions .15 .70
4210 @item @var{team} @tab optional; team on the which the inquiry is to be
4212 @item @var{image} @tab optional; the kind of the resulting integer array.
4216 This function follows TS18508. Because team-functionality is not yet
4217 implemented a null-pointer is passed for the @var{team} argument at the moment.
4221 @node _gfortran_caf_stopped_images
4222 @subsection @code{_gfortran_caf_stopped_images} --- Get an array of the indexes of the stopped images
4223 @cindex Coarray, _gfortran_caf_stopped_images
4226 @item @emph{Description}:
4227 Get an array of image indexes in the current @var{team} that have stopped. The
4228 array is sorted ascendingly. When @var{team} is not provided the current team
4229 is to be used. When @var{kind} is provided then the resulting array is of that
4230 integer kind else it is of default integer kind. The returns an unallocated
4231 size zero array when no images have failed.
4233 @item @emph{Syntax}:
4234 @code{int _gfortran_caf_stopped_images (caf_team_t * team, int * kind)}
4236 @item @emph{Arguments}:
4237 @multitable @columnfractions .15 .70
4238 @item @var{team} @tab optional; team on the which the inquiry is to be
4240 @item @var{image} @tab optional; the kind of the resulting integer array.
4244 This function follows TS18508. Because team-functionality is not yet
4245 implemented a null-pointer is passed for the @var{team} argument at the moment.
4249 @node _gfortran_caf_register
4250 @subsection @code{_gfortran_caf_register} --- Registering coarrays
4251 @cindex Coarray, _gfortran_caf_register
4254 @item @emph{Description}:
4255 Registers memory for a coarray and creates a token to identify the coarray. The
4256 routine is called for both coarrays with @code{SAVE} attribute and using an
4257 explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a
4258 @code{NULL} pointer, the function shall abort with printing an error message
4259 and starting the error termination. If no error occurs and @var{STAT} is
4260 present, it shall be set to zero. Otherwise, it shall be set to a positive
4261 value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing
4262 the failure. The routine shall register the memory provided in the
4263 @code{DATA}-component of the array descriptor @var{DESC}, when that component
4264 is non-@code{NULL}, else it shall allocate sufficient memory and provide a
4265 pointer to it in the @code{DATA}-component of @var{DESC}. The array descriptor
4266 has rank zero, when a scalar object is to be registered and the array
4267 descriptor may be invalid after the call to @code{_gfortran_caf_register}.
4268 When an array is to be allocated the descriptor persists.
4270 For @code{CAF_REGTYPE_COARRAY_STATIC} and @code{CAF_REGTYPE_COARRAY_ALLOC},
4271 the passed size is the byte size requested. For @code{CAF_REGTYPE_LOCK_STATIC},
4272 @code{CAF_REGTYPE_LOCK_ALLOC} and @code{CAF_REGTYPE_CRITICAL} it is the array
4273 size or one for a scalar.
4275 When @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} is used, then only a token
4276 for an allocatable or pointer component is created. The @code{SIZE} parameter
4277 is not used then. On the contrary when
4278 @code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} is specified, then the
4279 @var{token} needs to be registered by a previous call with regtype
4280 @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and either the memory specified
4281 in the @var{DESC}'s data-ptr is registered or allocate when the data-ptr is
4284 @item @emph{Syntax}:
4285 @code{void caf_register (size_t size, caf_register_t type, caf_token_t *token,
4286 gfc_descriptor_t *desc, int *stat, char *errmsg, size_t errmsg_len)}
4288 @item @emph{Arguments}:
4289 @multitable @columnfractions .15 .70
4290 @item @var{size} @tab For normal coarrays, the byte size of the coarray to be
4291 allocated; for lock types and event types, the number of elements.
4292 @item @var{type} @tab one of the caf_register_t types.
4293 @item @var{token} @tab intent(out) An opaque pointer identifying the coarray.
4294 @item @var{desc} @tab intent(inout) The (pseudo) array descriptor.
4295 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
4297 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4298 an error message; may be @code{NULL}
4299 @item @var{errmsg_len} @tab the buffer size of errmsg.
4303 Nonallocatable coarrays have to be registered prior use from remote images.
4304 In order to guarantee this, they have to be registered before the main
4305 program. This can be achieved by creating constructor functions. That is what
4306 GCC does such that also for nonallocatable coarrays the memory is allocated and
4307 no static memory is used. The token permits to identify the coarray; to the
4308 processor, the token is a nonaliasing pointer. The library can, for instance,
4309 store the base address of the coarray in the token, some handle or a more
4310 complicated struct. The library may also store the array descriptor
4311 @var{DESC} when its rank is non-zero.
4313 For lock types, the value shall only be used for checking the allocation
4314 status. Note that for critical blocks, the locking is only required on one
4315 image; in the locking statement, the processor shall always pass an
4316 image index of one for critical-block lock variables
4317 (@code{CAF_REGTYPE_CRITICAL}). For lock types and critical-block variables,
4318 the initial value shall be unlocked (or, respectively, not in critical
4319 section) such as the value false; for event types, the initial state should
4320 be no event, e.g. zero.
4324 @node _gfortran_caf_deregister
4325 @subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays
4326 @cindex Coarray, _gfortran_caf_deregister
4329 @item @emph{Description}:
4330 Called to free or deregister the memory of a coarray; the processor calls this
4331 function for automatic and explicit deallocation. In case of an error, this
4332 function shall fail with an error message, unless the @var{STAT} variable is
4333 not null. The library is only expected to free memory it allocated itself
4334 during a call to @code{_gfortran_caf_register}.
4336 @item @emph{Syntax}:
4337 @code{void caf_deregister (caf_token_t *token, caf_deregister_t type,
4338 int *stat, char *errmsg, size_t errmsg_len)}
4340 @item @emph{Arguments}:
4341 @multitable @columnfractions .15 .70
4342 @item @var{token} @tab the token to free.
4343 @item @var{type} @tab the type of action to take for the coarray. A
4344 @code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} is allowed only for allocatable or
4345 pointer components of derived type coarrays. The action only deallocates the
4346 local memory without deleting the token.
4347 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL
4348 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set
4349 to an error message; may be NULL
4350 @item @var{errmsg_len} @tab the buffer size of errmsg.
4354 For nonalloatable coarrays this function is never called. If a cleanup is
4355 required, it has to be handled via the finish, stop and error stop functions,
4356 and via destructors.
4360 @node _gfortran_caf_is_present
4361 @subsection @code{_gfortran_caf_is_present} --- Query whether an allocatable or pointer component in a derived type coarray is allocated
4362 @cindex Coarray, _gfortran_caf_is_present
4365 @item @emph{Description}:
4366 Used to query the coarray library whether an allocatable component in a derived
4367 type coarray is allocated on a remote image.
4369 @item @emph{Syntax}:
4370 @code{void _gfortran_caf_is_present (caf_token_t token, int image_index,
4371 gfc_reference_t *ref)}
4373 @item @emph{Arguments}:
4374 @multitable @columnfractions .15 .70
4375 @item @var{token} @tab An opaque pointer identifying the coarray.
4376 @item @var{image_index} @tab The ID of the remote image; must be a positive
4378 @item @var{ref} @tab A chain of references to address the allocatable or
4379 pointer component in the derived type coarray. The object reference needs to be
4380 a scalar or a full array reference, respectively.
4385 @node _gfortran_caf_send
4386 @subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image
4387 @cindex Coarray, _gfortran_caf_send
4390 @item @emph{Description}:
4391 Called to send a scalar, an array section or a whole array from a local
4392 to a remote image identified by the image_index.
4394 @item @emph{Syntax}:
4395 @code{void _gfortran_caf_send (caf_token_t token, size_t offset,
4396 int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
4397 gfc_descriptor_t *src, int dst_kind, int src_kind, bool may_require_tmp,
4400 @item @emph{Arguments}:
4401 @multitable @columnfractions .15 .70
4402 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4403 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
4404 shifted compared to the base address of the coarray.
4405 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4407 @item @var{dest} @tab intent(in) Array descriptor for the remote image for the
4408 bounds and the size. The @code{base_addr} shall not be accessed.
4409 @item @var{dst_vector} @tab intent(in) If not NULL, it contains the vector
4410 subscript of the destination array; the values are relative to the dimension
4411 triplet of the dest argument.
4412 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4413 transferred to the remote image
4414 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4415 @item @var{src_kind} @tab intent(in) Kind of the source argument
4416 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4417 it is known at compile time that the @var{dest} and @var{src} either cannot
4418 overlap or overlap (fully or partially) such that walking @var{src} and
4419 @var{dest} in element wise element order (honoring the stride value) will not
4420 lead to wrong results. Otherwise, the value is @code{true}.
4421 @item @var{stat} @tab intent(out) when non-NULL give the result of the
4422 operation, i.e., zero on success and non-zero on error. When NULL and an error
4423 occurs, then an error message is printed and the program is terminated.
4427 It is permitted to have @var{image_index} equal the current image; the memory
4428 of the send-to and the send-from might (partially) overlap in that case. The
4429 implementation has to take care that it handles this case, e.g. using
4430 @code{memmove} which handles (partially) overlapping memory. If
4431 @var{may_require_tmp} is true, the library might additionally create a
4432 temporary variable, unless additional checks show that this is not required
4433 (e.g. because walking backward is possible or because both arrays are
4434 contiguous and @code{memmove} takes care of overlap issues).
4436 Note that the assignment of a scalar to an array is permitted. In addition,
4437 the library has to handle numeric-type conversion and for strings, padding
4438 and different character kinds.
4442 @node _gfortran_caf_get
4443 @subsection @code{_gfortran_caf_get} --- Getting data from a remote image
4444 @cindex Coarray, _gfortran_caf_get
4447 @item @emph{Description}:
4448 Called to get an array section or a whole array from a remote,
4449 image identified by the image_index.
4451 @item @emph{Syntax}:
4452 @code{void _gfortran_caf_get (caf_token_t token, size_t offset,
4453 int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector,
4454 gfc_descriptor_t *dest, int src_kind, int dst_kind, bool may_require_tmp,
4457 @item @emph{Arguments}:
4458 @multitable @columnfractions .15 .70
4459 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4460 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
4461 shifted compared to the base address of the coarray.
4462 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4464 @item @var{dest} @tab intent(out) Array descriptor of the local array to store
4465 the data retrieved from the remote image
4466 @item @var{src} @tab intent(in) Array descriptor for the remote image for the
4467 bounds and the size. The @code{base_addr} shall not be accessed.
4468 @item @var{src_vector} @tab intent(in) If not NULL, it contains the vector
4469 subscript of the source array; the values are relative to the dimension
4470 triplet of the @var{src} argument.
4471 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4472 @item @var{src_kind} @tab intent(in) Kind of the source argument
4473 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4474 it is known at compile time that the @var{dest} and @var{src} either cannot
4475 overlap or overlap (fully or partially) such that walking @var{src} and
4476 @var{dest} in element wise element order (honoring the stride value) will not
4477 lead to wrong results. Otherwise, the value is @code{true}.
4478 @item @var{stat} @tab intent(out) When non-NULL give the result of the
4479 operation, i.e., zero on success and non-zero on error. When NULL and an error
4480 occurs, then an error message is printed and the program is terminated.
4484 It is permitted to have @var{image_index} equal the current image; the memory of
4485 the send-to and the send-from might (partially) overlap in that case. The
4486 implementation has to take care that it handles this case, e.g. using
4487 @code{memmove} which handles (partially) overlapping memory. If
4488 @var{may_require_tmp} is true, the library might additionally create a
4489 temporary variable, unless additional checks show that this is not required
4490 (e.g. because walking backward is possible or because both arrays are
4491 contiguous and @code{memmove} takes care of overlap issues).
4493 Note that the library has to handle numeric-type conversion and for strings,
4494 padding and different character kinds.
4498 @node _gfortran_caf_sendget
4499 @subsection @code{_gfortran_caf_sendget} --- Sending data between remote images
4500 @cindex Coarray, _gfortran_caf_sendget
4503 @item @emph{Description}:
4504 Called to send a scalar, an array section or a whole array from a remote image
4505 identified by the @var{src_image_index} to a remote image identified by the
4506 @var{dst_image_index}.
4508 @item @emph{Syntax}:
4509 @code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset,
4510 int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
4511 caf_token_t src_token, size_t src_offset, int src_image_index,
4512 gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind,
4513 bool may_require_tmp, int *stat)}
4515 @item @emph{Arguments}:
4516 @multitable @columnfractions .15 .70
4517 @item @var{dst_token} @tab intent(in) An opaque pointer identifying the
4518 destination coarray.
4519 @item @var{dst_offset} @tab intent(in) By which amount of bytes the actual data
4520 is shifted compared to the base address of the destination coarray.
4521 @item @var{dst_image_index} @tab intent(in) The ID of the destination remote
4522 image; must be a positive number.
4523 @item @var{dest} @tab intent(in) Array descriptor for the destination
4524 remote image for the bounds and the size. The @code{base_addr} shall not be
4526 @item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
4527 subscript of the destination array; the values are relative to the dimension
4528 triplet of the @var{dest} argument.
4529 @item @var{src_token} @tab intent(in) An opaque pointer identifying the source
4531 @item @var{src_offset} @tab intent(in) By which amount of bytes the actual data
4532 is shifted compared to the base address of the source coarray.
4533 @item @var{src_image_index} @tab intent(in) The ID of the source remote image;
4534 must be a positive number.
4535 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4536 transferred to the remote image.
4537 @item @var{src_vector} @tab intent(in) Array descriptor of the local array to
4538 be transferred to the remote image
4539 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4540 @item @var{src_kind} @tab intent(in) Kind of the source argument
4541 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4542 it is known at compile time that the @var{dest} and @var{src} either cannot
4543 overlap or overlap (fully or partially) such that walking @var{src} and
4544 @var{dest} in element wise element order (honoring the stride value) will not
4545 lead to wrong results. Otherwise, the value is @code{true}.
4546 @item @var{stat} @tab intent(out) when non-NULL give the result of the
4547 operation, i.e., zero on success and non-zero on error. When NULL and an error
4548 occurs, then an error message is printed and the program is terminated.
4552 It is permitted to have the same image index for both @var{src_image_index} and
4553 @var{dst_image_index}; the memory of the send-to and the send-from might
4554 (partially) overlap in that case. The implementation has to take care that it
4555 handles this case, e.g. using @code{memmove} which handles (partially)
4556 overlapping memory. If @var{may_require_tmp} is true, the library
4557 might additionally create a temporary variable, unless additional checks show
4558 that this is not required (e.g. because walking backward is possible or because
4559 both arrays are contiguous and @code{memmove} takes care of overlap issues).
4561 Note that the assignment of a scalar to an array is permitted. In addition,
4562 the library has to handle numeric-type conversion and for strings, padding and
4563 different character kinds.
4566 @node _gfortran_caf_send_by_ref
4567 @subsection @code{_gfortran_caf_send_by_ref} --- Sending data from a local image to a remote image with enhanced referencing options
4568 @cindex Coarray, _gfortran_caf_send_by_ref
4571 @item @emph{Description}:
4572 Called to send a scalar, an array section or a whole array from a local to a
4573 remote image identified by the @var{image_index}.
4575 @item @emph{Syntax}:
4576 @code{void _gfortran_caf_send_by_ref (caf_token_t token, int image_index,
4577 gfc_descriptor_t *src, caf_reference_t *refs, int dst_kind, int src_kind,
4578 bool may_require_tmp, bool dst_reallocatable, int *stat, int dst_type)}
4580 @item @emph{Arguments}:
4581 @multitable @columnfractions .15 .70
4582 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4583 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4585 @item @var{src} @tab intent(in) Array descriptor of the local array to be
4586 transferred to the remote image
4587 @item @var{refs} @tab intent(in) The references on the remote array to store
4588 the data given by src. Guaranteed to have at least one entry.
4589 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4590 @item @var{src_kind} @tab intent(in) Kind of the source argument
4591 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4592 it is known at compile time that the @var{dest} and @var{src} either cannot
4593 overlap or overlap (fully or partially) such that walking @var{src} and
4594 @var{dest} in element wise element order (honoring the stride value) will not
4595 lead to wrong results. Otherwise, the value is @code{true}.
4596 @item @var{dst_reallocatable} @tab intent(in) Set when the destination is of
4597 allocatable or pointer type and the refs will allow reallocation, i.e., the ref
4598 is a full array or component ref.
4599 @item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the
4600 operation, i.e., zero on success and non-zero on error. When @code{NULL} and
4601 an error occurs, then an error message is printed and the program is terminated.
4602 @item @var{dst_type} @tab intent(in) Give the type of the destination. When
4603 the destination is not an array, than the precise type, e.g. of a component in
4604 a derived type, is not known, but provided here.
4608 It is permitted to have @var{image_index} equal the current image; the memory of
4609 the send-to and the send-from might (partially) overlap in that case. The
4610 implementation has to take care that it handles this case, e.g. using
4611 @code{memmove} which handles (partially) overlapping memory. If
4612 @var{may_require_tmp} is true, the library might additionally create a
4613 temporary variable, unless additional checks show that this is not required
4614 (e.g. because walking backward is possible or because both arrays are
4615 contiguous and @code{memmove} takes care of overlap issues).
4617 Note that the assignment of a scalar to an array is permitted. In addition,
4618 the library has to handle numeric-type conversion and for strings, padding
4619 and different character kinds.
4621 Because of the more complicated references possible some operations may be
4622 unsupported by certain libraries. The library is expected to issue a precise
4623 error message why the operation is not permitted.
4627 @node _gfortran_caf_get_by_ref
4628 @subsection @code{_gfortran_caf_get_by_ref} --- Getting data from a remote image using enhanced references
4629 @cindex Coarray, _gfortran_caf_get_by_ref
4632 @item @emph{Description}:
4633 Called to get a scalar, an array section or a whole array from a remote image
4634 identified by the @var{image_index}.
4636 @item @emph{Syntax}:
4637 @code{void _gfortran_caf_get_by_ref (caf_token_t token, int image_index,
4638 caf_reference_t *refs, gfc_descriptor_t *dst, int dst_kind, int src_kind,
4639 bool may_require_tmp, bool dst_reallocatable, int *stat, int src_type)}
4641 @item @emph{Arguments}:
4642 @multitable @columnfractions .15 .70
4643 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4644 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4646 @item @var{refs} @tab intent(in) The references to apply to the remote structure
4648 @item @var{dst} @tab intent(in) Array descriptor of the local array to store
4649 the data transferred from the remote image. May be reallocated where needed
4650 and when @var{DST_REALLOCATABLE} allows it.
4651 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4652 @item @var{src_kind} @tab intent(in) Kind of the source argument
4653 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4654 it is known at compile time that the @var{dest} and @var{src} either cannot
4655 overlap or overlap (fully or partially) such that walking @var{src} and
4656 @var{dest} in element wise element order (honoring the stride value) will not
4657 lead to wrong results. Otherwise, the value is @code{true}.
4658 @item @var{dst_reallocatable} @tab intent(in) Set when @var{DST} is of
4659 allocatable or pointer type and its refs allow reallocation, i.e., the full
4660 array or a component is referenced.
4661 @item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the
4662 operation, i.e., zero on success and non-zero on error. When @code{NULL} and an
4663 error occurs, then an error message is printed and the program is terminated.
4664 @item @var{src_type} @tab intent(in) Give the type of the source. When the
4665 source is not an array, than the precise type, e.g. of a component in a
4666 derived type, is not known, but provided here.
4670 It is permitted to have @code{image_index} equal the current image; the memory
4671 of the send-to and the send-from might (partially) overlap in that case. The
4672 implementation has to take care that it handles this case, e.g. using
4673 @code{memmove} which handles (partially) overlapping memory. If
4674 @var{may_require_tmp} is true, the library might additionally create a
4675 temporary variable, unless additional checks show that this is not required
4676 (e.g. because walking backward is possible or because both arrays are
4677 contiguous and @code{memmove} takes care of overlap issues).
4679 Note that the library has to handle numeric-type conversion and for strings,
4680 padding and different character kinds.
4682 Because of the more complicated references possible some operations may be
4683 unsupported by certain libraries. The library is expected to issue a precise
4684 error message why the operation is not permitted.
4688 @node _gfortran_caf_sendget_by_ref
4689 @subsection @code{_gfortran_caf_sendget_by_ref} --- Sending data between remote images using enhanced references on both sides
4690 @cindex Coarray, _gfortran_caf_sendget_by_ref
4693 @item @emph{Description}:
4694 Called to send a scalar, an array section or a whole array from a remote image
4695 identified by the @var{src_image_index} to a remote image identified by the
4696 @var{dst_image_index}.
4698 @item @emph{Syntax}:
4699 @code{void _gfortran_caf_sendget_by_ref (caf_token_t dst_token,
4700 int dst_image_index, caf_reference_t *dst_refs,
4701 caf_token_t src_token, int src_image_index, caf_reference_t *src_refs,
4702 int dst_kind, int src_kind, bool may_require_tmp, int *dst_stat,
4703 int *src_stat, int dst_type, int src_type)}
4705 @item @emph{Arguments}:
4706 @multitable @columnfractions .15 .70
4707 @item @var{dst_token} @tab intent(in) An opaque pointer identifying the
4708 destination coarray.
4709 @item @var{dst_image_index} @tab intent(in) The ID of the destination remote
4710 image; must be a positive number.
4711 @item @var{dst_refs} @tab intent(in) The references on the remote array to store
4712 the data given by the source. Guaranteed to have at least one entry.
4713 @item @var{src_token} @tab intent(in) An opaque pointer identifying the source
4715 @item @var{src_image_index} @tab intent(in) The ID of the source remote image;
4716 must be a positive number.
4717 @item @var{src_refs} @tab intent(in) The references to apply to the remote
4718 structure to get the data.
4719 @item @var{dst_kind} @tab intent(in) Kind of the destination argument
4720 @item @var{src_kind} @tab intent(in) Kind of the source argument
4721 @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when
4722 it is known at compile time that the @var{dest} and @var{src} either cannot
4723 overlap or overlap (fully or partially) such that walking @var{src} and
4724 @var{dest} in element wise element order (honoring the stride value) will not
4725 lead to wrong results. Otherwise, the value is @code{true}.
4726 @item @var{dst_stat} @tab intent(out) when non-@code{NULL} give the result of
4727 the send-operation, i.e., zero on success and non-zero on error. When
4728 @code{NULL} and an error occurs, then an error message is printed and the
4729 program is terminated.
4730 @item @var{src_stat} @tab intent(out) When non-@code{NULL} give the result of
4731 the get-operation, i.e., zero on success and non-zero on error. When
4732 @code{NULL} and an error occurs, then an error message is printed and the
4733 program is terminated.
4734 @item @var{dst_type} @tab intent(in) Give the type of the destination. When
4735 the destination is not an array, than the precise type, e.g. of a component in
4736 a derived type, is not known, but provided here.
4737 @item @var{src_type} @tab intent(in) Give the type of the source. When the
4738 source is not an array, than the precise type, e.g. of a component in a
4739 derived type, is not known, but provided here.
4743 It is permitted to have the same image index for both @var{src_image_index} and
4744 @var{dst_image_index}; the memory of the send-to and the send-from might
4745 (partially) overlap in that case. The implementation has to take care that it
4746 handles this case, e.g. using @code{memmove} which handles (partially)
4747 overlapping memory. If @var{may_require_tmp} is true, the library
4748 might additionally create a temporary variable, unless additional checks show
4749 that this is not required (e.g. because walking backward is possible or because
4750 both arrays are contiguous and @code{memmove} takes care of overlap issues).
4752 Note that the assignment of a scalar to an array is permitted. In addition,
4753 the library has to handle numeric-type conversion and for strings, padding and
4754 different character kinds.
4756 Because of the more complicated references possible some operations may be
4757 unsupported by certain libraries. The library is expected to issue a precise
4758 error message why the operation is not permitted.
4762 @node _gfortran_caf_lock
4763 @subsection @code{_gfortran_caf_lock} --- Locking a lock variable
4764 @cindex Coarray, _gfortran_caf_lock
4767 @item @emph{Description}:
4768 Acquire a lock on the given image on a scalar locking variable or for the
4769 given array element for an array-valued variable. If the @var{acquired_lock}
4770 is @code{NULL}, the function returns after having obtained the lock. If it is
4771 non-@code{NULL}, then @var{acquired_lock} is assigned the value true (one) when
4772 the lock could be obtained and false (zero) otherwise. Locking a lock variable
4773 which has already been locked by the same image is an error.
4775 @item @emph{Syntax}:
4776 @code{void _gfortran_caf_lock (caf_token_t token, size_t index, int image_index,
4777 int *acquired_lock, int *stat, char *errmsg, size_t errmsg_len)}
4779 @item @emph{Arguments}:
4780 @multitable @columnfractions .15 .70
4781 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4782 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4783 scalars, it is always 0.
4784 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4786 @item @var{acquired_lock} @tab intent(out) If not NULL, it returns whether lock
4788 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
4789 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4790 an error message; may be NULL.
4791 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4795 This function is also called for critical blocks; for those, the array index
4796 is always zero and the image index is one. Libraries are permitted to use other
4797 images for critical-block locking variables.
4800 @node _gfortran_caf_unlock
4801 @subsection @code{_gfortran_caf_lock} --- Unlocking a lock variable
4802 @cindex Coarray, _gfortran_caf_unlock
4805 @item @emph{Description}:
4806 Release a lock on the given image on a scalar locking variable or for the
4807 given array element for an array-valued variable. Unlocking a lock variable
4808 which is unlocked or has been locked by a different image is an error.
4810 @item @emph{Syntax}:
4811 @code{void _gfortran_caf_unlock (caf_token_t token, size_t index, int image_index,
4812 int *stat, char *errmsg, size_t errmsg_len)}
4814 @item @emph{Arguments}:
4815 @multitable @columnfractions .15 .70
4816 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4817 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4818 scalars, it is always 0.
4819 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4821 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
4823 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4824 an error message; may be NULL.
4825 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4829 This function is also called for critical block; for those, the array index
4830 is always zero and the image index is one. Libraries are permitted to use other
4831 images for critical-block locking variables.
4834 @node _gfortran_caf_event_post
4835 @subsection @code{_gfortran_caf_event_post} --- Post an event
4836 @cindex Coarray, _gfortran_caf_event_post
4839 @item @emph{Description}:
4840 Increment the event count of the specified event variable.
4842 @item @emph{Syntax}:
4843 @code{void _gfortran_caf_event_post (caf_token_t token, size_t index,
4844 int image_index, int *stat, char *errmsg, size_t errmsg_len)}
4846 @item @emph{Arguments}:
4847 @multitable @columnfractions .15 .70
4848 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4849 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4850 scalars, it is always 0.
4851 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4852 positive number; zero indicates the current image, when accessed noncoindexed.
4853 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
4854 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4855 an error message; may be NULL.
4856 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4860 This acts like an atomic add of one to the remote image's event variable.
4861 The statement is an image-control statement but does not imply sync memory.
4862 Still, all preceding push communications of this image to the specified
4863 remote image have to be completed before @code{event_wait} on the remote
4869 @node _gfortran_caf_event_wait
4870 @subsection @code{_gfortran_caf_event_wait} --- Wait that an event occurred
4871 @cindex Coarray, _gfortran_caf_event_wait
4874 @item @emph{Description}:
4875 Wait until the event count has reached at least the specified
4876 @var{until_count}; if so, atomically decrement the event variable by this
4879 @item @emph{Syntax}:
4880 @code{void _gfortran_caf_event_wait (caf_token_t token, size_t index,
4881 int until_count, int *stat, char *errmsg, size_t errmsg_len)}
4883 @item @emph{Arguments}:
4884 @multitable @columnfractions .15 .70
4885 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4886 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4887 scalars, it is always 0.
4888 @item @var{until_count} @tab intent(in) The number of events which have to be
4889 available before the function returns.
4890 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
4891 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4892 an error message; may be NULL.
4893 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4897 This function only operates on a local coarray. It acts like a loop checking
4898 atomically the value of the event variable, breaking if the value is greater
4899 or equal the requested number of counts. Before the function returns, the
4900 event variable has to be decremented by the requested @var{until_count} value.
4901 A possible implementation would be a busy loop for a certain number of spins
4902 (possibly depending on the number of threads relative to the number of available
4903 cores) followed by another waiting strategy such as a sleeping wait (possibly
4904 with an increasing number of sleep time) or, if possible, a futex wait.
4906 The statement is an image-control statement but does not imply sync memory.
4907 Still, all preceding push communications of this image to the specified
4908 remote image have to be completed before @code{event_wait} on the remote
4914 @node _gfortran_caf_event_query
4915 @subsection @code{_gfortran_caf_event_query} --- Query event count
4916 @cindex Coarray, _gfortran_caf_event_query
4919 @item @emph{Description}:
4920 Return the event count of the specified event variable.
4922 @item @emph{Syntax}:
4923 @code{void _gfortran_caf_event_query (caf_token_t token, size_t index,
4924 int image_index, int *count, int *stat)}
4926 @item @emph{Arguments}:
4927 @multitable @columnfractions .15 .70
4928 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
4929 @item @var{index} @tab intent(in) Array index; first array index is 0. For
4930 scalars, it is always 0.
4931 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
4932 positive number; zero indicates the current image when accessed noncoindexed.
4933 @item @var{count} @tab intent(out) The number of events currently posted to
4935 @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
4939 The typical use is to check the local event variable to only call
4940 @code{event_wait} when the data is available. However, a coindexed variable
4941 is permitted; there is no ordering or synchronization implied. It acts like
4942 an atomic fetch of the value of the event variable.
4947 @node _gfortran_caf_sync_all
4948 @subsection @code{_gfortran_caf_sync_all} --- All-image barrier
4949 @cindex Coarray, _gfortran_caf_sync_all
4952 @item @emph{Description}:
4953 Synchronization of all images in the current team; the program only continues
4954 on a given image after this function has been called on all images of the
4955 current team. Additionally, it ensures that all pending data transfers of
4956 previous segment have completed.
4958 @item @emph{Syntax}:
4959 @code{void _gfortran_caf_sync_all (int *stat, char *errmsg, size_t errmsg_len)}
4961 @item @emph{Arguments}:
4962 @multitable @columnfractions .15 .70
4963 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4964 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4965 an error message; may be NULL.
4966 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
4972 @node _gfortran_caf_sync_images
4973 @subsection @code{_gfortran_caf_sync_images} --- Barrier for selected images
4974 @cindex Coarray, _gfortran_caf_sync_images
4977 @item @emph{Description}:
4978 Synchronization between the specified images; the program only continues on a
4979 given image after this function has been called on all images specified for
4980 that image. Note that one image can wait for all other images in the current
4981 team (e.g. via @code{sync images(*)}) while those only wait for that specific
4982 image. Additionally, @code{sync images} ensures that all pending data
4983 transfers of previous segments have completed.
4985 @item @emph{Syntax}:
4986 @code{void _gfortran_caf_sync_images (int count, int images[], int *stat,
4987 char *errmsg, size_t errmsg_len)}
4989 @item @emph{Arguments}:
4990 @multitable @columnfractions .15 .70
4991 @item @var{count} @tab intent(in) The number of images which are provided in
4992 the next argument. For a zero-sized array, the value is zero. For
4993 @code{sync images (*)}, the value is @math{-1}.
4994 @item @var{images} @tab intent(in) An array with the images provided by the
4995 user. If @var{count} is zero, a NULL pointer is passed.
4996 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
4997 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
4998 an error message; may be NULL.
4999 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5005 @node _gfortran_caf_sync_memory
5006 @subsection @code{_gfortran_caf_sync_memory} --- Wait for completion of segment-memory operations
5007 @cindex Coarray, _gfortran_caf_sync_memory
5010 @item @emph{Description}:
5011 Acts as optimization barrier between different segments. It also ensures that
5012 all pending memory operations of this image have been completed.
5014 @item @emph{Syntax}:
5015 @code{void _gfortran_caf_sync_memory (int *stat, char *errmsg, size_t errmsg_len)}
5017 @item @emph{Arguments}:
5018 @multitable @columnfractions .15 .70
5019 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5020 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5021 an error message; may be NULL.
5022 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5025 @item @emph{NOTE} A simple implementation could be
5026 @code{__asm__ __volatile__ ("":::"memory")} to prevent code movements.
5031 @node _gfortran_caf_error_stop
5032 @subsection @code{_gfortran_caf_error_stop} --- Error termination with exit code
5033 @cindex Coarray, _gfortran_caf_error_stop
5036 @item @emph{Description}:
5037 Invoked for an @code{ERROR STOP} statement which has an integer argument. The
5038 function should terminate the program with the specified exit code.
5041 @item @emph{Syntax}:
5042 @code{void _gfortran_caf_error_stop (int error)}
5044 @item @emph{Arguments}:
5045 @multitable @columnfractions .15 .70
5046 @item @var{error} @tab intent(in) The exit status to be used.
5052 @node _gfortran_caf_error_stop_str
5053 @subsection @code{_gfortran_caf_error_stop_str} --- Error termination with string
5054 @cindex Coarray, _gfortran_caf_error_stop_str
5057 @item @emph{Description}:
5058 Invoked for an @code{ERROR STOP} statement which has a string as argument. The
5059 function should terminate the program with a nonzero-exit code.
5061 @item @emph{Syntax}:
5062 @code{void _gfortran_caf_error_stop (const char *string, size_t len)}
5064 @item @emph{Arguments}:
5065 @multitable @columnfractions .15 .70
5066 @item @var{string} @tab intent(in) the error message (not zero terminated)
5067 @item @var{len} @tab intent(in) the length of the string
5073 @node _gfortran_caf_fail_image
5074 @subsection @code{_gfortran_caf_fail_image} --- Mark the image failed and end its execution
5075 @cindex Coarray, _gfortran_caf_fail_image
5078 @item @emph{Description}:
5079 Invoked for an @code{FAIL IMAGE} statement. The function should terminate the
5082 @item @emph{Syntax}:
5083 @code{void _gfortran_caf_fail_image ()}
5086 This function follows TS18508.
5091 @node _gfortran_caf_atomic_define
5092 @subsection @code{_gfortran_caf_atomic_define} --- Atomic variable assignment
5093 @cindex Coarray, _gfortran_caf_atomic_define
5096 @item @emph{Description}:
5097 Assign atomically a value to an integer or logical variable.
5099 @item @emph{Syntax}:
5100 @code{void _gfortran_caf_atomic_define (caf_token_t token, size_t offset,
5101 int image_index, void *value, int *stat, int type, int kind)}
5103 @item @emph{Arguments}:
5104 @multitable @columnfractions .15 .70
5105 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5106 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5107 shifted compared to the base address of the coarray.
5108 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5109 positive number; zero indicates the current image when used noncoindexed.
5110 @item @var{value} @tab intent(in) the value to be assigned, passed by reference
5111 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5112 @item @var{type} @tab intent(in) The data type, i.e. @code{BT_INTEGER} (1) or
5113 @code{BT_LOGICAL} (2).
5114 @item @var{kind} @tab intent(in) The kind value (only 4; always @code{int})
5120 @node _gfortran_caf_atomic_ref
5121 @subsection @code{_gfortran_caf_atomic_ref} --- Atomic variable reference
5122 @cindex Coarray, _gfortran_caf_atomic_ref
5125 @item @emph{Description}:
5126 Reference atomically a value of a kind-4 integer or logical variable.
5128 @item @emph{Syntax}:
5129 @code{void _gfortran_caf_atomic_ref (caf_token_t token, size_t offset,
5130 int image_index, void *value, int *stat, int type, int kind)}
5132 @item @emph{Arguments}:
5133 @multitable @columnfractions .15 .70
5134 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5135 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5136 shifted compared to the base address of the coarray.
5137 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5138 positive number; zero indicates the current image when used noncoindexed.
5139 @item @var{value} @tab intent(out) The variable assigned the atomically
5140 referenced variable.
5141 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5142 @item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
5143 @code{BT_LOGICAL} (2).
5144 @item @var{kind} @tab The kind value (only 4; always @code{int})
5150 @node _gfortran_caf_atomic_cas
5151 @subsection @code{_gfortran_caf_atomic_cas} --- Atomic compare and swap
5152 @cindex Coarray, _gfortran_caf_atomic_cas
5155 @item @emph{Description}:
5156 Atomic compare and swap of a kind-4 integer or logical variable. Assigns
5157 atomically the specified value to the atomic variable, if the latter has
5158 the value specified by the passed condition value.
5160 @item @emph{Syntax}:
5161 @code{void _gfortran_caf_atomic_cas (caf_token_t token, size_t offset,
5162 int image_index, void *old, void *compare, void *new_val, int *stat,
5163 int type, int kind)}
5165 @item @emph{Arguments}:
5166 @multitable @columnfractions .15 .70
5167 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5168 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5169 shifted compared to the base address of the coarray.
5170 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5171 positive number; zero indicates the current image when used noncoindexed.
5172 @item @var{old} @tab intent(out) The value which the atomic variable had
5173 just before the cas operation.
5174 @item @var{compare} @tab intent(in) The value used for comparision.
5175 @item @var{new_val} @tab intent(in) The new value for the atomic variable,
5176 assigned to the atomic variable, if @code{compare} equals the value of the
5178 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5179 @item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or
5180 @code{BT_LOGICAL} (2).
5181 @item @var{kind} @tab intent(in) The kind value (only 4; always @code{int})
5187 @node _gfortran_caf_atomic_op
5188 @subsection @code{_gfortran_caf_atomic_op} --- Atomic operation
5189 @cindex Coarray, _gfortran_caf_atomic_op
5192 @item @emph{Description}:
5193 Apply an operation atomically to an atomic integer or logical variable.
5194 After the operation, @var{old} contains the value just before the operation,
5195 which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the @code{value} to
5196 the atomic integer variable or does a bitwise AND, OR or exclusive OR
5197 between the atomic variable and @var{value}; the result is then stored in the
5200 @item @emph{Syntax}:
5201 @code{void _gfortran_caf_atomic_op (int op, caf_token_t token, size_t offset,
5202 int image_index, void *value, void *old, int *stat, int type, int kind)}
5204 @item @emph{Arguments}:
5205 @multitable @columnfractions .15 .70
5206 @item @var{op} @tab intent(in) the operation to be performed; possible values
5207 @code{GFC_CAF_ATOMIC_ADD} (1), @code{GFC_CAF_ATOMIC_AND} (2),
5208 @code{GFC_CAF_ATOMIC_OR} (3), @code{GFC_CAF_ATOMIC_XOR} (4).
5209 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
5210 @item @var{offset} @tab intent(in) By which amount of bytes the actual data is
5211 shifted compared to the base address of the coarray.
5212 @item @var{image_index} @tab intent(in) The ID of the remote image; must be a
5213 positive number; zero indicates the current image when used noncoindexed.
5214 @item @var{old} @tab intent(out) The value which the atomic variable had
5215 just before the atomic operation.
5216 @item @var{val} @tab intent(in) The new value for the atomic variable,
5217 assigned to the atomic variable, if @code{compare} equals the value of the
5219 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5220 @item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or
5221 @code{BT_LOGICAL} (2)
5222 @item @var{kind} @tab intent(in) the kind value (only 4; always @code{int})
5229 @node _gfortran_caf_co_broadcast
5230 @subsection @code{_gfortran_caf_co_broadcast} --- Sending data to all images
5231 @cindex Coarray, _gfortran_caf_co_broadcast
5234 @item @emph{Description}:
5235 Distribute a value from a given image to all other images in the team. Has to
5236 be called collectively.
5238 @item @emph{Syntax}:
5239 @code{void _gfortran_caf_co_broadcast (gfc_descriptor_t *a,
5240 int source_image, int *stat, char *errmsg, size_t errmsg_len)}
5242 @item @emph{Arguments}:
5243 @multitable @columnfractions .15 .70
5244 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5245 broadcasted (on @var{source_image}) or to be received (other images).
5246 @item @var{source_image} @tab intent(in) The ID of the image from which the
5247 data should be broadcasted.
5248 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5249 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5250 an error message; may be NULL.
5251 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg.
5257 @node _gfortran_caf_co_max
5258 @subsection @code{_gfortran_caf_co_max} --- Collective maximum reduction
5259 @cindex Coarray, _gfortran_caf_co_max
5262 @item @emph{Description}:
5263 Calculates for each array element of the variable @var{a} the maximum
5264 value for that element in the current team; if @var{result_image} has the
5265 value 0, the result shall be stored on all images, otherwise, only on the
5266 specified image. This function operates on numeric values and character
5269 @item @emph{Syntax}:
5270 @code{void _gfortran_caf_co_max (gfc_descriptor_t *a, int result_image,
5271 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5273 @item @emph{Arguments}:
5274 @multitable @columnfractions .15 .70
5275 @item @var{a} @tab intent(inout) An array descriptor for the data to be
5276 processed. On the destination image(s) the result overwrites the old content.
5277 @item @var{result_image} @tab intent(in) The ID of the image to which the
5278 reduced value should be copied to; if zero, it has to be copied to all images.
5279 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5280 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5281 an error message; may be NULL.
5282 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5283 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5287 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5288 all images except of the specified one become undefined; hence, the library may
5294 @node _gfortran_caf_co_min
5295 @subsection @code{_gfortran_caf_co_min} --- Collective minimum reduction
5296 @cindex Coarray, _gfortran_caf_co_min
5299 @item @emph{Description}:
5300 Calculates for each array element of the variable @var{a} the minimum
5301 value for that element in the current team; if @var{result_image} has the
5302 value 0, the result shall be stored on all images, otherwise, only on the
5303 specified image. This function operates on numeric values and character
5306 @item @emph{Syntax}:
5307 @code{void _gfortran_caf_co_min (gfc_descriptor_t *a, int result_image,
5308 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5310 @item @emph{Arguments}:
5311 @multitable @columnfractions .15 .70
5312 @item @var{a} @tab intent(inout) An array descriptor for the data to be
5313 processed. On the destination image(s) the result overwrites the old content.
5314 @item @var{result_image} @tab intent(in) The ID of the image to which the
5315 reduced value should be copied to; if zero, it has to be copied to all images.
5316 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5317 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5318 an error message; may be NULL.
5319 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5320 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5324 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5325 all images except of the specified one become undefined; hence, the library may
5331 @node _gfortran_caf_co_sum
5332 @subsection @code{_gfortran_caf_co_sum} --- Collective summing reduction
5333 @cindex Coarray, _gfortran_caf_co_sum
5336 @item @emph{Description}:
5337 Calculates for each array element of the variable @var{a} the sum of all
5338 values for that element in the current team; if @var{result_image} has the
5339 value 0, the result shall be stored on all images, otherwise, only on the
5340 specified image. This function operates on numeric values only.
5342 @item @emph{Syntax}:
5343 @code{void _gfortran_caf_co_sum (gfc_descriptor_t *a, int result_image,
5344 int *stat, char *errmsg, size_t errmsg_len)}
5346 @item @emph{Arguments}:
5347 @multitable @columnfractions .15 .70
5348 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5349 processed. On the destination image(s) the result overwrites the old content.
5350 @item @var{result_image} @tab intent(in) The ID of the image to which the
5351 reduced value should be copied to; if zero, it has to be copied to all images.
5352 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5353 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5354 an error message; may be NULL.
5355 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5359 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5360 all images except of the specified one become undefined; hence, the library may
5366 @node _gfortran_caf_co_reduce
5367 @subsection @code{_gfortran_caf_co_reduce} --- Generic collective reduction
5368 @cindex Coarray, _gfortran_caf_co_reduce
5371 @item @emph{Description}:
5372 Calculates for each array element of the variable @var{a} the reduction
5373 value for that element in the current team; if @var{result_image} has the
5374 value 0, the result shall be stored on all images, otherwise, only on the
5375 specified image. The @var{opr} is a pure function doing a mathematically
5376 commutative and associative operation.
5378 The @var{opr_flags} denote the following; the values are bitwise ored.
5379 @code{GFC_CAF_BYREF} (1) if the result should be returned
5380 by reference; @code{GFC_CAF_HIDDENLEN} (2) whether the result and argument
5381 string lengths shall be specified as hidden arguments;
5382 @code{GFC_CAF_ARG_VALUE} (4) whether the arguments shall be passed by value,
5383 @code{GFC_CAF_ARG_DESC} (8) whether the arguments shall be passed by descriptor.
5386 @item @emph{Syntax}:
5387 @code{void _gfortran_caf_co_reduce (gfc_descriptor_t *a,
5388 void * (*opr) (void *, void *), int opr_flags, int result_image,
5389 int *stat, char *errmsg, int a_len, size_t errmsg_len)}
5391 @item @emph{Arguments}:
5392 @multitable @columnfractions .15 .70
5393 @item @var{a} @tab intent(inout) An array descriptor with the data to be
5394 processed. On the destination image(s) the result overwrites the old content.
5395 @item @var{opr} @tab intent(in) Function pointer to the reduction function
5396 @item @var{opr_flags} @tab intent(in) Flags regarding the reduction function
5397 @item @var{result_image} @tab intent(in) The ID of the image to which the
5398 reduced value should be copied to; if zero, it has to be copied to all images.
5399 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
5400 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
5401 an error message; may be NULL.
5402 @item @var{a_len} @tab intent(in) the string length of argument @var{a}
5403 @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
5407 If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
5408 all images except of the specified one become undefined; hence, the library may
5411 For character arguments, the result is passed as first argument, followed
5412 by the result string length, next come the two string arguments, followed
5413 by the two hidden string length arguments. With C binding, there are no hidden
5414 arguments and by-reference passing and either only a single character is passed
5415 or an array descriptor.
5419 @c Intrinsic Procedures
5420 @c ---------------------------------------------------------------------
5422 @include intrinsic.texi
5429 @c ---------------------------------------------------------------------
5431 @c ---------------------------------------------------------------------
5434 @unnumbered Contributing
5435 @cindex Contributing
5437 Free software is only possible if people contribute to efforts
5439 We're always in need of more people helping out with ideas
5440 and comments, writing documentation and contributing code.
5442 If you want to contribute to GNU Fortran,
5443 have a look at the long lists of projects you can take on.
5444 Some of these projects are small,
5445 some of them are large;
5446 some are completely orthogonal to the rest of what is
5447 happening on GNU Fortran,
5448 but others are ``mainstream'' projects in need of enthusiastic hackers.
5449 All of these projects are important!
5450 We will eventually get around to the things here,
5451 but they are also things doable by someone who is willing and able.
5460 @section Contributors to GNU Fortran
5461 @cindex Contributors
5465 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
5466 also the initiator of the whole project. Thanks Andy!
5467 Most of the interface with GCC was written by @emph{Paul Brook}.
5469 The following individuals have contributed code and/or
5470 ideas and significant help to the GNU Fortran project
5471 (in alphabetical order):
5474 @item Janne Blomqvist
5475 @item Steven Bosscher
5478 @item Fran@,{c}ois-Xavier Coudert
5482 @item Bernhard Fischer
5484 @item Richard Guenther
5485 @item Richard Henderson
5486 @item Katherine Holcomb
5488 @item Niels Kristian Bech Jensen
5489 @item Steven Johnson
5490 @item Steven G. Kargl
5498 @item Christopher D. Rickett
5499 @item Richard Sandiford
5500 @item Tobias Schl@"uter
5509 The following people have contributed bug reports,
5510 smaller or larger patches,
5511 and much needed feedback and encouragement for the
5512 GNU Fortran project:
5516 @item Dominique d'Humi@`eres
5518 @item Erik Schnetter
5519 @item Gerhard Steinmetz
5520 @item Joost VandeVondele
5523 Many other individuals have helped debug,
5524 test and improve the GNU Fortran compiler over the past few years,
5525 and we welcome you to do the same!
5526 If you already have done so,
5527 and you would like to see your name listed in the
5528 list above, please contact us.
5536 @item Help build the test suite
5537 Solicit more code for donation to the test suite: the more extensive the
5538 testsuite, the smaller the risk of breaking things in the future! We can
5539 keep code private on request.
5541 @item Bug hunting/squishing
5542 Find bugs and write more test cases! Test cases are especially very
5543 welcome, because it allows us to concentrate on fixing bugs instead of
5544 isolating them. Going through the bugzilla database at
5545 @url{https://gcc.gnu.org/@/bugzilla/} to reduce testcases posted there and
5546 add more information (for example, for which version does the testcase
5547 work, for which versions does it fail?) is also very helpful.
5549 @item Missing features
5550 For a larger project, consider working on the missing features required for
5551 Fortran language standards compliance (@pxref{Standards}), or contributing
5552 to the implementation of extensions such as OpenMP (@pxref{OpenMP}) or
5553 OpenACC (@pxref{OpenACC}) that are under active development. Again,
5554 contributing test cases for these features is useful too!
5559 @c ---------------------------------------------------------------------
5560 @c GNU General Public License
5561 @c ---------------------------------------------------------------------
5563 @include gpl_v3.texi
5567 @c ---------------------------------------------------------------------
5568 @c GNU Free Documentation License
5569 @c ---------------------------------------------------------------------
5575 @c ---------------------------------------------------------------------
5576 @c Funding Free Software
5577 @c ---------------------------------------------------------------------
5579 @include funding.texi
5581 @c ---------------------------------------------------------------------
5583 @c ---------------------------------------------------------------------
5586 @unnumbered Option Index
5587 @command{gfortran}'s command line options are indexed here without any
5588 initial @samp{-} or @samp{--}. Where an option has both positive and
5589 negative forms (such as -foption and -fno-option), relevant entries in
5590 the manual are indexed under the most appropriate form; it may sometimes
5591 be useful to look up both forms.
5595 @unnumbered Keyword Index