1 \input texinfo @c -*-texinfo-*-
3 @setfilename gfortran.info
4 @set copyrights-gfortran 1999-2014
6 @include gcc-common.texi
8 @settitle The GNU Fortran Compiler
10 @c Create a separate index for command line options
12 @c Merge the standard indexes into a single one.
19 @c TODO: The following "Part" definitions are included here temporarily
20 @c until they are incorporated into the official Texinfo distribution.
21 @c They borrow heavily from Texinfo's \unnchapentry definitions.
28 \vglue\titlepagetopglue
30 \leftline{Part #1:@* #2}
31 \vskip4pt \hrule height 4pt width \hsize \vskip4pt
33 \writetocentry{part}{#2}{#1}
36 \writetocentry{blankpart}{}{}
38 % Part TOC-entry definition for summary contents.
39 \gdef\dosmallpartentry#1#2#3#4{%
40 \vskip .5\baselineskip plus.2\baselineskip
43 \tocentry{Part #2: #1}{\doshortpageno\bgroup#4\egroup}
46 \gdef\dosmallblankpartentry#1#2#3#4{%
47 \vskip .5\baselineskip plus.2\baselineskip
49 % Part TOC-entry definition for regular contents. This has to be
50 % equated to an existing entry to not cause problems when the PDF
52 \gdef\dopartentry#1#2#3#4{%
53 \unnchapentry{Part #2: #1}{}{#3}{#4}
55 \gdef\doblankpartentry#1#2#3#4{}
60 @c Use with @@smallbook.
62 @c %** start of document
64 @c Cause even numbered pages to be printed on the left hand side of
65 @c the page and odd numbered pages to be printed on the right hand
66 @c side of the page. Using this, you can print on both sides of a
67 @c sheet of paper and have the text on the same part of the sheet.
69 @c The text on right hand pages is pushed towards the right hand
70 @c margin and the text on left hand pages is pushed toward the left
72 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
75 @c \global\bindingoffset=0.75in
76 @c \global\normaloffset =0.75in
80 Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc.
82 Permission is granted to copy, distribute and/or modify this document
83 under the terms of the GNU Free Documentation License, Version 1.3 or
84 any later version published by the Free Software Foundation; with the
85 Invariant Sections being ``Funding Free Software'', the Front-Cover
86 Texts being (a) (see below), and with the Back-Cover Texts being (b)
87 (see below). A copy of the license is included in the section entitled
88 ``GNU Free Documentation License''.
90 (a) The FSF's Front-Cover Text is:
94 (b) The FSF's Back-Cover Text is:
96 You have freedom to copy and modify this GNU Manual, like GNU
97 software. Copies published by the Free Software Foundation raise
98 funds for GNU development.
102 @dircategory Software development
104 * gfortran: (gfortran). The GNU Fortran Compiler.
106 This file documents the use and the internals of
107 the GNU Fortran compiler, (@command{gfortran}).
109 Published by the Free Software Foundation
110 51 Franklin Street, Fifth Floor
111 Boston, MA 02110-1301 USA
117 @setchapternewpage odd
119 @title Using GNU Fortran
121 @author The @t{gfortran} team
123 @vskip 0pt plus 1filll
124 Published by the Free Software Foundation@*
125 51 Franklin Street, Fifth Floor@*
126 Boston, MA 02110-1301, USA@*
127 @c Last printed ??ber, 19??.@*
128 @c Printed copies are available for $? each.@*
134 @c TODO: The following "Part" definitions are included here temporarily
135 @c until they are incorporated into the official Texinfo distribution.
138 \global\let\partentry=\dosmallpartentry
139 \global\let\blankpartentry=\dosmallblankpartentry
144 \global\let\partentry=\dopartentry
145 \global\let\blankpartentry=\doblankpartentry
151 @c ---------------------------------------------------------------------
152 @c TexInfo table of contents.
153 @c ---------------------------------------------------------------------
160 This manual documents the use of @command{gfortran},
161 the GNU Fortran compiler. You can find in this manual how to invoke
162 @command{gfortran}, as well as its features and incompatibilities.
165 @emph{Warning:} This document, and the compiler it describes, are still
166 under development. While efforts are made to keep it up-to-date, it might
167 not accurately reflect the status of the most recent GNU Fortran compiler.
171 @comment When you add a new menu item, please keep the right hand
172 @comment aligned to the same column. Do not use tabs. This provides
173 @comment better formatting.
178 Part I: Invoking GNU Fortran
179 * Invoking GNU Fortran:: Command options supported by @command{gfortran}.
180 * Runtime:: Influencing runtime behavior with environment variables.
182 Part II: Language Reference
183 * Fortran 2003 and 2008 status:: Fortran 2003 and 2008 features supported by GNU Fortran.
184 * Compiler Characteristics:: User-visible implementation details.
185 * Extensions:: Language extensions implemented by GNU Fortran.
186 * Mixed-Language Programming:: Interoperability with C
187 * Coarray Programming::
188 * Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran.
189 * Intrinsic Modules:: Intrinsic modules supported by GNU Fortran.
191 * Contributing:: How you can help.
192 * Copying:: GNU General Public License says
193 how you can copy and share GNU Fortran.
194 * GNU Free Documentation License::
195 How you can copy and share this manual.
196 * Funding:: How to help assure continued work for free software.
197 * Option Index:: Index of command line options
198 * Keyword Index:: Index of concepts
202 @c ---------------------------------------------------------------------
204 @c ---------------------------------------------------------------------
207 @chapter Introduction
209 @c The following duplicates the text on the TexInfo table of contents.
211 This manual documents the use of @command{gfortran}, the GNU Fortran
212 compiler. You can find in this manual how to invoke @command{gfortran},
213 as well as its features and incompatibilities.
216 @emph{Warning:} This document, and the compiler it describes, are still
217 under development. While efforts are made to keep it up-to-date, it
218 might not accurately reflect the status of the most recent GNU Fortran
223 The GNU Fortran compiler front end was
224 designed initially as a free replacement for,
225 or alternative to, the Unix @command{f95} command;
226 @command{gfortran} is the command you will use to invoke the compiler.
229 * About GNU Fortran:: What you should know about the GNU Fortran compiler.
230 * GNU Fortran and GCC:: You can compile Fortran, C, or other programs.
231 * Preprocessing and conditional compilation:: The Fortran preprocessor
232 * GNU Fortran and G77:: Why we chose to start from scratch.
233 * Project Status:: Status of GNU Fortran, roadmap, proposed extensions.
234 * Standards:: Standards supported by GNU Fortran.
238 @c ---------------------------------------------------------------------
240 @c ---------------------------------------------------------------------
242 @node About GNU Fortran
243 @section About GNU Fortran
245 The GNU Fortran compiler supports the Fortran 77, 90 and 95 standards
246 completely, parts of the Fortran 2003 and Fortran 2008 standards, and
247 several vendor extensions. The development goal is to provide the
252 Read a user's program,
253 stored in a file and containing instructions written
254 in Fortran 77, Fortran 90, Fortran 95, Fortran 2003 or Fortran 2008.
255 This file contains @dfn{source code}.
258 Translate the user's program into instructions a computer
259 can carry out more quickly than it takes to translate the
260 instructions in the first
261 place. The result after compilation of a program is
263 code designed to be efficiently translated and processed
264 by a machine such as your computer.
265 Humans usually are not as good writing machine code
266 as they are at writing Fortran (or C++, Ada, or Java),
267 because it is easy to make tiny mistakes writing machine code.
270 Provide the user with information about the reasons why
271 the compiler is unable to create a binary from the source code.
272 Usually this will be the case if the source code is flawed.
273 The Fortran 90 standard requires that the compiler can point out
274 mistakes to the user.
275 An incorrect usage of the language causes an @dfn{error message}.
277 The compiler will also attempt to diagnose cases where the
278 user's program contains a correct usage of the language,
279 but instructs the computer to do something questionable.
280 This kind of diagnostics message is called a @dfn{warning message}.
283 Provide optional information about the translation passes
284 from the source code to machine code.
285 This can help a user of the compiler to find the cause of
286 certain bugs which may not be obvious in the source code,
287 but may be more easily found at a lower level compiler output.
288 It also helps developers to find bugs in the compiler itself.
291 Provide information in the generated machine code that can
292 make it easier to find bugs in the program (using a debugging tool,
293 called a @dfn{debugger}, such as the GNU Debugger @command{gdb}).
296 Locate and gather machine code already generated to
297 perform actions requested by statements in the user's program.
298 This machine code is organized into @dfn{modules} and is located
299 and @dfn{linked} to the user program.
302 The GNU Fortran compiler consists of several components:
306 A version of the @command{gcc} command
307 (which also might be installed as the system's @command{cc} command)
308 that also understands and accepts Fortran source code.
309 The @command{gcc} command is the @dfn{driver} program for
310 all the languages in the GNU Compiler Collection (GCC);
312 you can compile the source code of any language for
313 which a front end is available in GCC.
316 The @command{gfortran} command itself,
317 which also might be installed as the
318 system's @command{f95} command.
319 @command{gfortran} is just another driver program,
320 but specifically for the Fortran compiler only.
321 The difference with @command{gcc} is that @command{gfortran}
322 will automatically link the correct libraries to your program.
325 A collection of run-time libraries.
326 These libraries contain the machine code needed to support
327 capabilities of the Fortran language that are not directly
328 provided by the machine code generated by the
329 @command{gfortran} compilation phase,
330 such as intrinsic functions and subroutines,
331 and routines for interaction with files and the operating system.
332 @c and mechanisms to spawn,
333 @c unleash and pause threads in parallelized code.
336 The Fortran compiler itself, (@command{f951}).
337 This is the GNU Fortran parser and code generator,
338 linked to and interfaced with the GCC backend library.
339 @command{f951} ``translates'' the source code to
340 assembler code. You would typically not use this
342 instead, the @command{gcc} or @command{gfortran} driver
343 programs will call it for you.
347 @c ---------------------------------------------------------------------
348 @c GNU Fortran and GCC
349 @c ---------------------------------------------------------------------
351 @node GNU Fortran and GCC
352 @section GNU Fortran and GCC
353 @cindex GNU Compiler Collection
356 GNU Fortran is a part of GCC, the @dfn{GNU Compiler Collection}. GCC
357 consists of a collection of front ends for various languages, which
358 translate the source code into a language-independent form called
359 @dfn{GENERIC}. This is then processed by a common middle end which
360 provides optimization, and then passed to one of a collection of back
361 ends which generate code for different computer architectures and
364 Functionally, this is implemented with a driver program (@command{gcc})
365 which provides the command-line interface for the compiler. It calls
366 the relevant compiler front-end program (e.g., @command{f951} for
367 Fortran) for each file in the source code, and then calls the assembler
368 and linker as appropriate to produce the compiled output. In a copy of
369 GCC which has been compiled with Fortran language support enabled,
370 @command{gcc} will recognize files with @file{.f}, @file{.for}, @file{.ftn},
371 @file{.f90}, @file{.f95}, @file{.f03} and @file{.f08} extensions as
372 Fortran source code, and compile it accordingly. A @command{gfortran}
373 driver program is also provided, which is identical to @command{gcc}
374 except that it automatically links the Fortran runtime libraries into the
377 Source files with @file{.f}, @file{.for}, @file{.fpp}, @file{.ftn}, @file{.F},
378 @file{.FOR}, @file{.FPP}, and @file{.FTN} extensions are treated as fixed form.
379 Source files with @file{.f90}, @file{.f95}, @file{.f03}, @file{.f08},
380 @file{.F90}, @file{.F95}, @file{.F03} and @file{.F08} extensions are
381 treated as free form. The capitalized versions of either form are run
382 through preprocessing. Source files with the lower case @file{.fpp}
383 extension are also run through preprocessing.
385 This manual specifically documents the Fortran front end, which handles
386 the programming language's syntax and semantics. The aspects of GCC
387 which relate to the optimization passes and the back-end code generation
388 are documented in the GCC manual; see
389 @ref{Top,,Introduction,gcc,Using the GNU Compiler Collection (GCC)}.
390 The two manuals together provide a complete reference for the GNU
394 @c ---------------------------------------------------------------------
395 @c Preprocessing and conditional compilation
396 @c ---------------------------------------------------------------------
398 @node Preprocessing and conditional compilation
399 @section Preprocessing and conditional compilation
402 @cindex Conditional compilation
403 @cindex Preprocessing
404 @cindex preprocessor, include file handling
406 Many Fortran compilers including GNU Fortran allow passing the source code
407 through a C preprocessor (CPP; sometimes also called the Fortran preprocessor,
408 FPP) to allow for conditional compilation. In the case of GNU Fortran,
409 this is the GNU C Preprocessor in the traditional mode. On systems with
410 case-preserving file names, the preprocessor is automatically invoked if the
411 filename extension is @file{.F}, @file{.FOR}, @file{.FTN}, @file{.fpp},
412 @file{.FPP}, @file{.F90}, @file{.F95}, @file{.F03} or @file{.F08}. To manually
413 invoke the preprocessor on any file, use @option{-cpp}, to disable
414 preprocessing on files where the preprocessor is run automatically, use
417 If a preprocessed file includes another file with the Fortran @code{INCLUDE}
418 statement, the included file is not preprocessed. To preprocess included
419 files, use the equivalent preprocessor statement @code{#include}.
421 If GNU Fortran invokes the preprocessor, @code{__GFORTRAN__}
422 is defined and @code{__GNUC__}, @code{__GNUC_MINOR__} and
423 @code{__GNUC_PATCHLEVEL__} can be used to determine the version of the
424 compiler. See @ref{Top,,Overview,cpp,The C Preprocessor} for details.
426 While CPP is the de-facto standard for preprocessing Fortran code,
427 Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines
428 Conditional Compilation, which is not widely used and not directly
429 supported by the GNU Fortran compiler. You can use the program coco
430 to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}).
433 @c ---------------------------------------------------------------------
434 @c GNU Fortran and G77
435 @c ---------------------------------------------------------------------
437 @node GNU Fortran and G77
438 @section GNU Fortran and G77
440 @cindex @command{g77}
442 The GNU Fortran compiler is the successor to @command{g77}, the Fortran
443 77 front end included in GCC prior to version 4. It is an entirely new
444 program that has been designed to provide Fortran 95 support and
445 extensibility for future Fortran language standards, as well as providing
446 backwards compatibility for Fortran 77 and nearly all of the GNU language
447 extensions supported by @command{g77}.
450 @c ---------------------------------------------------------------------
452 @c ---------------------------------------------------------------------
455 @section Project Status
458 As soon as @command{gfortran} can parse all of the statements correctly,
459 it will be in the ``larva'' state.
460 When we generate code, the ``puppa'' state.
461 When @command{gfortran} is done,
462 we'll see if it will be a beautiful butterfly,
463 or just a big bug....
465 --Andy Vaught, April 2000
468 The start of the GNU Fortran 95 project was announced on
469 the GCC homepage in March 18, 2000
470 (even though Andy had already been working on it for a while,
473 The GNU Fortran compiler is able to compile nearly all
474 standard-compliant Fortran 95, Fortran 90, and Fortran 77 programs,
475 including a number of standard and non-standard extensions, and can be
476 used on real-world programs. In particular, the supported extensions
477 include OpenMP, Cray-style pointers, and several Fortran 2003 and Fortran
478 2008 features, including TR 15581. However, it is still under
479 development and has a few remaining rough edges.
481 At present, the GNU Fortran compiler passes the
482 @uref{http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html,
483 NIST Fortran 77 Test Suite}, and produces acceptable results on the
484 @uref{http://www.netlib.org/lapack/faq.html#1.21, LAPACK Test Suite}.
485 It also provides respectable performance on
486 the @uref{http://www.polyhedron.com/fortran-compiler-comparisons/polyhedron-benchmark-suite,
488 compiler benchmarks} and the
489 @uref{http://www.netlib.org/benchmark/livermore,
490 Livermore Fortran Kernels test}. It has been used to compile a number of
491 large real-world programs, including
492 @uref{http://hirlam.org/, the HARMONIE and HIRLAM weather forecasting code} and
493 @uref{http://physical-chemistry.scb.uwa.edu.au/tonto/wiki/index.php/Main_Page,
494 the Tonto quantum chemistry package}; see
495 @url{https://gcc.gnu.org/@/wiki/@/GfortranApps} for an extended list.
497 Among other things, the GNU Fortran compiler is intended as a replacement
498 for G77. At this point, nearly all programs that could be compiled with
499 G77 can be compiled with GNU Fortran, although there are a few minor known
502 The primary work remaining to be done on GNU Fortran falls into three
503 categories: bug fixing (primarily regarding the treatment of invalid code
504 and providing useful error messages), improving the compiler optimizations
505 and the performance of compiled code, and extending the compiler to support
506 future standards---in particular, Fortran 2003 and Fortran 2008.
509 @c ---------------------------------------------------------------------
511 @c ---------------------------------------------------------------------
518 * Varying Length Character Strings::
521 The GNU Fortran compiler implements
522 ISO/IEC 1539:1997 (Fortran 95). As such, it can also compile essentially all
523 standard-compliant Fortran 90 and Fortran 77 programs. It also supports
524 the ISO/IEC TR-15581 enhancements to allocatable arrays.
526 GNU Fortran also have a partial support for ISO/IEC 1539-1:2004 (Fortran
527 2003), ISO/IEC 1539-1:2010 (Fortran 2008), the Technical Specification
528 @code{Further Interoperability of Fortran with C} (ISO/IEC TS 29113:2012).
529 Full support of those standards and future Fortran standards is planned.
530 The current status of the support is can be found in the
531 @ref{Fortran 2003 status}, @ref{Fortran 2008 status} and
532 @ref{TS 29113 status} sections of the documentation.
534 Additionally, the GNU Fortran compilers supports the OpenMP specification
535 (version 4.0, @url{http://openmp.org/@/wp/@/openmp-specifications/}).
537 @node Varying Length Character Strings
538 @subsection Varying Length Character Strings
539 @cindex Varying length character strings
540 @cindex Varying length strings
541 @cindex strings, varying length
543 The Fortran 95 standard specifies in Part 2 (ISO/IEC 1539-2:2000)
544 varying length character strings. While GNU Fortran currently does not
545 support such strings directly, there exist two Fortran implementations
546 for them, which work with GNU Fortran. They can be found at
547 @uref{http://www.fortran.com/@/iso_varying_string.f95} and at
548 @uref{ftp://ftp.nag.co.uk/@/sc22wg5/@/ISO_VARYING_STRING/}.
550 Deferred-length character strings of Fortran 2003 supports part of
551 the features of @code{ISO_VARYING_STRING} and should be considered as
552 replacement. (Namely, allocatable or pointers of the type
553 @code{character(len=:)}.)
556 @c =====================================================================
557 @c PART I: INVOCATION REFERENCE
558 @c =====================================================================
561 \part{I}{Invoking GNU Fortran}
564 @c ---------------------------------------------------------------------
566 @c ---------------------------------------------------------------------
571 @c ---------------------------------------------------------------------
573 @c ---------------------------------------------------------------------
576 @chapter Runtime: Influencing runtime behavior with environment variables
577 @cindex environment variable
579 The behavior of the @command{gfortran} can be influenced by
580 environment variables.
582 Malformed environment variables are silently ignored.
585 * TMPDIR:: Directory for scratch files
586 * GFORTRAN_STDIN_UNIT:: Unit number for standard input
587 * GFORTRAN_STDOUT_UNIT:: Unit number for standard output
588 * GFORTRAN_STDERR_UNIT:: Unit number for standard error
589 * GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units.
590 * GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units.
591 * GFORTRAN_SHOW_LOCUS:: Show location for runtime errors
592 * GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted
593 * GFORTRAN_DEFAULT_RECL:: Default record length for new files
594 * GFORTRAN_LIST_SEPARATOR:: Separator for list output
595 * GFORTRAN_CONVERT_UNIT:: Set endianness for unformatted I/O
596 * GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors
600 @section @env{TMPDIR}---Directory for scratch files
602 When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to
603 create the file in one of the potential directories by testing each
604 directory in the order below.
608 The environment variable @env{TMPDIR}, if it exists.
611 On the MinGW target, the directory returned by the @code{GetTempPath}
612 function. Alternatively, on the Cygwin target, the @env{TMP} and
613 @env{TEMP} environment variables, if they exist, in that order.
616 The @code{P_tmpdir} macro if it is defined, otherwise the directory
620 @node GFORTRAN_STDIN_UNIT
621 @section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input
623 This environment variable can be used to select the unit number
624 preconnected to standard input. This must be a positive integer.
625 The default value is 5.
627 @node GFORTRAN_STDOUT_UNIT
628 @section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output
630 This environment variable can be used to select the unit number
631 preconnected to standard output. This must be a positive integer.
632 The default value is 6.
634 @node GFORTRAN_STDERR_UNIT
635 @section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error
637 This environment variable can be used to select the unit number
638 preconnected to standard error. This must be a positive integer.
639 The default value is 0.
641 @node GFORTRAN_UNBUFFERED_ALL
642 @section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units
644 This environment variable controls whether all I/O is unbuffered. If
645 the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is
646 unbuffered. This will slow down small sequential reads and writes. If
647 the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered.
650 @node GFORTRAN_UNBUFFERED_PRECONNECTED
651 @section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units
653 The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls
654 whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) is unbuffered. If
655 the first letter is @samp{y}, @samp{Y} or @samp{1}, I/O is unbuffered. This
656 will slow down small sequential reads and writes. If the first letter
657 is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. This is the default.
659 @node GFORTRAN_SHOW_LOCUS
660 @section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors
662 If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and
663 line numbers for runtime errors are printed. If the first letter is
664 @samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers
665 for runtime errors. The default is to print the location.
667 @node GFORTRAN_OPTIONAL_PLUS
668 @section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted
670 If the first letter is @samp{y}, @samp{Y} or @samp{1},
671 a plus sign is printed
672 where permitted by the Fortran standard. If the first letter
673 is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed
674 in most cases. Default is not to print plus signs.
676 @node GFORTRAN_DEFAULT_RECL
677 @section @env{GFORTRAN_DEFAULT_RECL}---Default record length for new files
679 This environment variable specifies the default record length, in
680 bytes, for files which are opened without a @code{RECL} tag in the
681 @code{OPEN} statement. This must be a positive integer. The
682 default value is 1073741824 bytes (1 GB).
684 @node GFORTRAN_LIST_SEPARATOR
685 @section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output
687 This environment variable specifies the separator when writing
688 list-directed output. It may contain any number of spaces and
689 at most one comma. If you specify this on the command line,
690 be sure to quote spaces, as in
692 $ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out
694 when @command{a.out} is the compiled Fortran program that you want to run.
695 Default is a single space.
697 @node GFORTRAN_CONVERT_UNIT
698 @section @env{GFORTRAN_CONVERT_UNIT}---Set endianness for unformatted I/O
700 By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible
701 to change the representation of data for unformatted files.
702 The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable is:
704 GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ;
705 mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ;
706 exception: mode ':' unit_list | unit_list ;
707 unit_list: unit_spec | unit_list unit_spec ;
708 unit_spec: INTEGER | INTEGER '-' INTEGER ;
710 The variable consists of an optional default mode, followed by
711 a list of optional exceptions, which are separated by semicolons
712 from the preceding default and each other. Each exception consists
713 of a format and a comma-separated list of units. Valid values for
714 the modes are the same as for the @code{CONVERT} specifier:
717 @item @code{NATIVE} Use the native format. This is the default.
718 @item @code{SWAP} Swap between little- and big-endian.
719 @item @code{LITTLE_ENDIAN} Use the little-endian format
720 for unformatted files.
721 @item @code{BIG_ENDIAN} Use the big-endian format for unformatted files.
723 A missing mode for an exception is taken to mean @code{BIG_ENDIAN}.
724 Examples of values for @env{GFORTRAN_CONVERT_UNIT} are:
726 @item @code{'big_endian'} Do all unformatted I/O in big_endian mode.
727 @item @code{'little_endian;native:10-20,25'} Do all unformatted I/O
728 in little_endian mode, except for units 10 to 20 and 25, which are in
730 @item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native.
733 Setting the environment variables should be done on the command
734 line or via the @command{export}
735 command for @command{sh}-compatible shells and via @command{setenv}
736 for @command{csh}-compatible shells.
738 Example for @command{sh}:
741 $ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out
744 Example code for @command{csh}:
747 % setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20'
751 Using anything but the native representation for unformatted data
752 carries a significant speed overhead. If speed in this area matters
753 to you, it is best if you use this only for data that needs to be
756 @xref{CONVERT specifier}, for an alternative way to specify the
757 data representation for unformatted files. @xref{Runtime Options}, for
758 setting a default data representation for the whole program. The
759 @code{CONVERT} specifier overrides the @option{-fconvert} compile options.
761 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
762 environment variable will override the CONVERT specifier in the
763 open statement}. This is to give control over data formats to
764 users who do not have the source code of their program available.
766 @node GFORTRAN_ERROR_BACKTRACE
767 @section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors
769 If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to @samp{y},
770 @samp{Y} or @samp{1} (only the first letter is relevant) then a
771 backtrace is printed when a serious run-time error occurs. To disable
772 the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}.
773 Default is to print a backtrace unless the @option{-fno-backtrace}
774 compile option was used.
776 @c =====================================================================
777 @c PART II: LANGUAGE REFERENCE
778 @c =====================================================================
781 \part{II}{Language Reference}
784 @c ---------------------------------------------------------------------
785 @c Fortran 2003 and 2008 Status
786 @c ---------------------------------------------------------------------
788 @node Fortran 2003 and 2008 status
789 @chapter Fortran 2003 and 2008 Status
792 * Fortran 2003 status::
793 * Fortran 2008 status::
797 @node Fortran 2003 status
798 @section Fortran 2003 status
800 GNU Fortran supports several Fortran 2003 features; an incomplete
801 list can be found below. See also the
802 @uref{https://gcc.gnu.org/wiki/Fortran2003, wiki page} about Fortran 2003.
805 @item Procedure pointers including procedure-pointer components with
806 @code{PASS} attribute.
808 @item Procedures which are bound to a derived type (type-bound procedures)
809 including @code{PASS}, @code{PROCEDURE} and @code{GENERIC}, and
810 operators bound to a type.
812 @item Abstract interfaces and type extension with the possibility to
813 override type-bound procedures or to have deferred binding.
815 @item Polymorphic entities (``@code{CLASS}'') for derived types and unlimited
816 polymorphism (``@code{CLASS(*)}'') -- including @code{SAME_TYPE_AS},
817 @code{EXTENDS_TYPE_OF} and @code{SELECT TYPE} for scalars and arrays and
820 @item Generic interface names, which have the same name as derived types,
821 are now supported. This allows one to write constructor functions. Note
822 that Fortran does not support static constructor functions. For static
823 variables, only default initialization or structure-constructor
824 initialization are available.
826 @item The @code{ASSOCIATE} construct.
828 @item Interoperability with C including enumerations,
830 @item In structure constructors the components with default values may be
833 @item Extensions to the @code{ALLOCATE} statement, allowing for a
834 type-specification with type parameter and for allocation and initialization
835 from a @code{SOURCE=} expression; @code{ALLOCATE} and @code{DEALLOCATE}
836 optionally return an error message string via @code{ERRMSG=}.
838 @item Reallocation on assignment: If an intrinsic assignment is
839 used, an allocatable variable on the left-hand side is automatically allocated
840 (if unallocated) or reallocated (if the shape is different). Currently, scalar
841 deferred character length left-hand sides are correctly handled but arrays
842 are not yet fully implemented.
844 @item Deferred-length character variables and scalar deferred-length character
845 components of derived types are supported. (Note that array-valued compoents
846 are not yet implemented.)
848 @item Transferring of allocations via @code{MOVE_ALLOC}.
850 @item The @code{PRIVATE} and @code{PUBLIC} attributes may be given individually
851 to derived-type components.
853 @item In pointer assignments, the lower bound may be specified and
854 the remapping of elements is supported.
856 @item For pointers an @code{INTENT} may be specified which affect the
857 association status not the value of the pointer target.
859 @item Intrinsics @code{command_argument_count}, @code{get_command},
860 @code{get_command_argument}, and @code{get_environment_variable}.
862 @item Support for Unicode characters (ISO 10646) and UTF-8, including
863 the @code{SELECTED_CHAR_KIND} and @code{NEW_LINE} intrinsic functions.
865 @item Support for binary, octal and hexadecimal (BOZ) constants in the
866 intrinsic functions @code{INT}, @code{REAL}, @code{CMPLX} and @code{DBLE}.
868 @item Support for namelist variables with allocatable and pointer
869 attribute and nonconstant length type parameter.
872 @cindex array, constructors
874 Array constructors using square brackets. That is, @code{[...]} rather
875 than @code{(/.../)}. Type-specification for array constructors like
876 @code{(/ some-type :: ... /)}.
878 @item Extensions to the specification and initialization expressions,
879 including the support for intrinsics with real and complex arguments.
881 @item Support for the asynchronous input/output syntax; however, the
882 data transfer is currently always synchronously performed.
885 @cindex @code{FLUSH} statement
886 @cindex statement, @code{FLUSH}
887 @code{FLUSH} statement.
890 @cindex @code{IOMSG=} specifier
891 @code{IOMSG=} specifier for I/O statements.
894 @cindex @code{ENUM} statement
895 @cindex @code{ENUMERATOR} statement
896 @cindex statement, @code{ENUM}
897 @cindex statement, @code{ENUMERATOR}
898 @opindex @code{fshort-enums}
899 Support for the declaration of enumeration constants via the
900 @code{ENUM} and @code{ENUMERATOR} statements. Interoperability with
901 @command{gcc} is guaranteed also for the case where the
902 @command{-fshort-enums} command line option is given.
909 @cindex @code{ALLOCATABLE} dummy arguments
910 @code{ALLOCATABLE} dummy arguments.
912 @cindex @code{ALLOCATABLE} function results
913 @code{ALLOCATABLE} function results
915 @cindex @code{ALLOCATABLE} components of derived types
916 @code{ALLOCATABLE} components of derived types
920 @cindex @code{STREAM} I/O
921 @cindex @code{ACCESS='STREAM'} I/O
922 The @code{OPEN} statement supports the @code{ACCESS='STREAM'} specifier,
923 allowing I/O without any record structure.
926 Namelist input/output for internal files.
928 @item Minor I/O features: Rounding during formatted output, using of
929 a decimal comma instead of a decimal point, setting whether a plus sign
930 should appear for positive numbers. On systems where @code{strtod} honours
931 the rounding mode, the rounding mode is also supported for input.
934 @cindex @code{PROTECTED} statement
935 @cindex statement, @code{PROTECTED}
936 The @code{PROTECTED} statement and attribute.
939 @cindex @code{VALUE} statement
940 @cindex statement, @code{VALUE}
941 The @code{VALUE} statement and attribute.
944 @cindex @code{VOLATILE} statement
945 @cindex statement, @code{VOLATILE}
946 The @code{VOLATILE} statement and attribute.
949 @cindex @code{IMPORT} statement
950 @cindex statement, @code{IMPORT}
951 The @code{IMPORT} statement, allowing to import
952 host-associated derived types.
954 @item The intrinsic modules @code{ISO_FORTRAN_ENVIRONMENT} is supported,
955 which contains parameters of the I/O units, storage sizes. Additionally,
956 procedures for C interoperability are available in the @code{ISO_C_BINDING}
960 @cindex @code{USE, INTRINSIC} statement
961 @cindex statement, @code{USE, INTRINSIC}
962 @cindex @code{ISO_FORTRAN_ENV} statement
963 @cindex statement, @code{ISO_FORTRAN_ENV}
964 @code{USE} statement with @code{INTRINSIC} and @code{NON_INTRINSIC}
965 attribute; supported intrinsic modules: @code{ISO_FORTRAN_ENV},
966 @code{ISO_C_BINDING}, @code{OMP_LIB} and @code{OMP_LIB_KINDS}.
969 Renaming of operators in the @code{USE} statement.
974 @node Fortran 2008 status
975 @section Fortran 2008 status
977 The latest version of the Fortran standard is ISO/IEC 1539-1:2010, informally
978 known as Fortran 2008. The official version is available from International
979 Organization for Standardization (ISO) or its national member organizations.
980 The the final draft (FDIS) can be downloaded free of charge from
981 @url{http://www.nag.co.uk/@/sc22wg5/@/links.html}. Fortran is developed by the
982 Working Group 5 of Sub-Committee 22 of the Joint Technical Committee 1 of the
983 International Organization for Standardization and the International
984 Electrotechnical Commission (IEC). This group is known as
985 @uref{http://www.nag.co.uk/sc22wg5/, WG5}.
987 The GNU Fortran compiler supports several of the new features of Fortran 2008;
988 the @uref{https://gcc.gnu.org/wiki/Fortran2008Status, wiki} has some information
989 about the current Fortran 2008 implementation status. In particular, the
990 following is implemented.
993 @item The @option{-std=f2008} option and support for the file extensions
994 @file{.f08} and @file{.F08}.
996 @item The @code{OPEN} statement now supports the @code{NEWUNIT=} option,
997 which returns a unique file unit, thus preventing inadvertent use of the
998 same unit in different parts of the program.
1000 @item The @code{g0} format descriptor and unlimited format items.
1002 @item The mathematical intrinsics @code{ASINH}, @code{ACOSH}, @code{ATANH},
1003 @code{ERF}, @code{ERFC}, @code{GAMMA}, @code{LOG_GAMMA}, @code{BESSEL_J0},
1004 @code{BESSEL_J1}, @code{BESSEL_JN}, @code{BESSEL_Y0}, @code{BESSEL_Y1},
1005 @code{BESSEL_YN}, @code{HYPOT}, @code{NORM2}, and @code{ERFC_SCALED}.
1007 @item Using complex arguments with @code{TAN}, @code{SINH}, @code{COSH},
1008 @code{TANH}, @code{ASIN}, @code{ACOS}, and @code{ATAN} is now possible;
1009 @code{ATAN}(@var{Y},@var{X}) is now an alias for @code{ATAN2}(@var{Y},@var{X}).
1011 @item Support of the @code{PARITY} intrinsic functions.
1013 @item The following bit intrinsics: @code{LEADZ} and @code{TRAILZ} for
1014 counting the number of leading and trailing zero bits, @code{POPCNT} and
1015 @code{POPPAR} for counting the number of one bits and returning the parity;
1016 @code{BGE}, @code{BGT}, @code{BLE}, and @code{BLT} for bitwise comparisons;
1017 @code{DSHIFTL} and @code{DSHIFTR} for combined left and right shifts,
1018 @code{MASKL} and @code{MASKR} for simple left and right justified masks,
1019 @code{MERGE_BITS} for a bitwise merge using a mask, @code{SHIFTA},
1020 @code{SHIFTL} and @code{SHIFTR} for shift operations, and the
1021 transformational bit intrinsics @code{IALL}, @code{IANY} and @code{IPARITY}.
1023 @item Support of the @code{EXECUTE_COMMAND_LINE} intrinsic subroutine.
1025 @item Support for the @code{STORAGE_SIZE} intrinsic inquiry function.
1027 @item The @code{INT@{8,16,32@}} and @code{REAL@{32,64,128@}} kind type
1028 parameters and the array-valued named constants @code{INTEGER_KINDS},
1029 @code{LOGICAL_KINDS}, @code{REAL_KINDS} and @code{CHARACTER_KINDS} of
1030 the intrinsic module @code{ISO_FORTRAN_ENV}.
1032 @item The module procedures @code{C_SIZEOF} of the intrinsic module
1033 @code{ISO_C_BINDINGS} and @code{COMPILER_VERSION} and @code{COMPILER_OPTIONS}
1034 of @code{ISO_FORTRAN_ENV}.
1036 @item Coarray support for serial programs with @option{-fcoarray=single} flag
1037 and experimental support for multiple images with the @option{-fcoarray=lib}
1040 @item The @code{DO CONCURRENT} construct is supported.
1042 @item The @code{BLOCK} construct is supported.
1044 @item The @code{STOP} and the new @code{ERROR STOP} statements now
1045 support all constant expressions. Both show the signals which were signaling
1048 @item Support for the @code{CONTIGUOUS} attribute.
1050 @item Support for @code{ALLOCATE} with @code{MOLD}.
1052 @item Support for the @code{IMPURE} attribute for procedures, which
1053 allows for @code{ELEMENTAL} procedures without the restrictions of
1056 @item Null pointers (including @code{NULL()}) and not-allocated variables
1057 can be used as actual argument to optional non-pointer, non-allocatable
1058 dummy arguments, denoting an absent argument.
1060 @item Non-pointer variables with @code{TARGET} attribute can be used as
1061 actual argument to @code{POINTER} dummies with @code{INTENT(IN)}.
1063 @item Pointers including procedure pointers and those in a derived
1064 type (pointer components) can now be initialized by a target instead
1065 of only by @code{NULL}.
1067 @item The @code{EXIT} statement (with construct-name) can be now be
1068 used to leave not only the @code{DO} but also the @code{ASSOCIATE},
1069 @code{BLOCK}, @code{IF}, @code{SELECT CASE} and @code{SELECT TYPE}
1072 @item Internal procedures can now be used as actual argument.
1074 @item Minor features: obsolesce diagnostics for @code{ENTRY} with
1075 @option{-std=f2008}; a line may start with a semicolon; for internal
1076 and module procedures @code{END} can be used instead of
1077 @code{END SUBROUTINE} and @code{END FUNCTION}; @code{SELECTED_REAL_KIND}
1078 now also takes a @code{RADIX} argument; intrinsic types are supported
1079 for @code{TYPE}(@var{intrinsic-type-spec}); multiple type-bound procedures
1080 can be declared in a single @code{PROCEDURE} statement; implied-shape
1081 arrays are supported for named constants (@code{PARAMETER}).
1086 @node TS 29113 status
1087 @section Technical Specification 29113 Status
1089 GNU Fortran supports some of the new features of the Technical
1090 Specification (TS) 29113 on Further Interoperability of Fortran with C.
1091 The @uref{https://gcc.gnu.org/wiki/TS29113Status, wiki} has some information
1092 about the current TS 29113 implementation status. In particular, the
1093 following is implemented.
1095 See also @ref{Further Interoperability of Fortran with C}.
1098 @item The @option{-std=f2008ts} option.
1100 @item The @code{OPTIONAL} attribute is allowed for dummy arguments
1101 of @code{BIND(C) procedures.}
1103 @item The @code{RANK} intrinsic is supported.
1105 @item GNU Fortran's implementation for variables with @code{ASYNCHRONOUS}
1106 attribute is compatible with TS 29113.
1108 @item Assumed types (@code{TYPE(*)}.
1110 @item Assumed-rank (@code{DIMENSION(..)}). However, the array descriptor
1111 of the TS is not yet supported.
1116 @c ---------------------------------------------------------------------
1117 @c Compiler Characteristics
1118 @c ---------------------------------------------------------------------
1120 @node Compiler Characteristics
1121 @chapter Compiler Characteristics
1123 This chapter describes certain characteristics of the GNU Fortran
1124 compiler, that are not specified by the Fortran standard, but which
1125 might in some way or another become visible to the programmer.
1128 * KIND Type Parameters::
1129 * Internal representation of LOGICAL variables::
1130 * Thread-safety of the runtime library::
1131 * Data consistency and durability::
1135 @node KIND Type Parameters
1136 @section KIND Type Parameters
1139 The @code{KIND} type parameters supported by GNU Fortran for the primitive
1145 1, 2, 4, 8*, 16*, default: 4**
1148 1, 2, 4, 8*, 16*, default: 4**
1151 4, 8, 10*, 16*, default: 4***
1154 4, 8, 10*, 16*, default: 4***
1156 @item DOUBLE PRECISION
1157 4, 8, 10*, 16*, default: 8***
1165 * not available on all systems @*
1166 ** unless @option{-fdefault-integer-8} is used @*
1167 *** unless @option{-fdefault-real-8} is used (see @ref{Fortran Dialect Options})
1170 The @code{KIND} value matches the storage size in bytes, except for
1171 @code{COMPLEX} where the storage size is twice as much (or both real and
1172 imaginary part are a real value of the given size). It is recommended to use
1173 the @ref{SELECTED_CHAR_KIND}, @ref{SELECTED_INT_KIND} and
1174 @ref{SELECTED_REAL_KIND} intrinsics or the @code{INT8}, @code{INT16},
1175 @code{INT32}, @code{INT64}, @code{REAL32}, @code{REAL64}, and @code{REAL128}
1176 parameters of the @code{ISO_FORTRAN_ENV} module instead of the concrete values.
1177 The available kind parameters can be found in the constant arrays
1178 @code{CHARACTER_KINDS}, @code{INTEGER_KINDS}, @code{LOGICAL_KINDS} and
1179 @code{REAL_KINDS} in the @ref{ISO_FORTRAN_ENV} module. For C interoperability,
1180 the kind parameters of the @ref{ISO_C_BINDING} module should be used.
1183 @node Internal representation of LOGICAL variables
1184 @section Internal representation of LOGICAL variables
1185 @cindex logical, variable representation
1187 The Fortran standard does not specify how variables of @code{LOGICAL}
1188 type are represented, beyond requiring that @code{LOGICAL} variables
1189 of default kind have the same storage size as default @code{INTEGER}
1190 and @code{REAL} variables. The GNU Fortran internal representation is
1193 A @code{LOGICAL(KIND=N)} variable is represented as an
1194 @code{INTEGER(KIND=N)} variable, however, with only two permissible
1195 values: @code{1} for @code{.TRUE.} and @code{0} for
1196 @code{.FALSE.}. Any other integer value results in undefined behavior.
1198 See also @ref{Argument passing conventions} and @ref{Interoperability with C}.
1201 @node Thread-safety of the runtime library
1202 @section Thread-safety of the runtime library
1203 @cindex thread-safety, threads
1205 GNU Fortran can be used in programs with multiple threads, e.g.@: by
1206 using OpenMP, by calling OS thread handling functions via the
1207 @code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code
1208 being called from a multi-threaded program.
1210 The GNU Fortran runtime library, (@code{libgfortran}), supports being
1211 called concurrently from multiple threads with the following
1214 During library initialization, the C @code{getenv} function is used,
1215 which need not be thread-safe. Similarly, the @code{getenv}
1216 function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and
1217 @code{GETENV} intrinsics. It is the responsibility of the user to
1218 ensure that the environment is not being updated concurrently when any
1219 of these actions are taking place.
1221 The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are
1222 implemented with the @code{system} function, which need not be
1223 thread-safe. It is the responsibility of the user to ensure that
1224 @code{system} is not called concurrently.
1226 For platforms not supporting thread-safe POSIX functions, further
1227 functionality might not be thread-safe. For details, please consult
1228 the documentation for your operating system.
1230 The GNU Fortran runtime library uses various C library functions that
1231 depend on the locale, such as @code{strtod} and @code{snprintf}. In
1232 order to work correctly in locale-aware programs that set the locale
1233 using @code{setlocale}, the locale is reset to the default ``C''
1234 locale while executing a formatted @code{READ} or @code{WRITE}
1235 statement. On targets supporting the POSIX 2008 per-thread locale
1236 functions (e.g. @code{newlocale}, @code{uselocale},
1237 @code{freelocale}), these are used and thus the global locale set
1238 using @code{setlocale} or the per-thread locales in other threads are
1239 not affected. However, on targets lacking this functionality, the
1240 global LC_NUMERIC locale is set to ``C'' during the formatted I/O.
1241 Thus, on such targets it's not safe to call @code{setlocale}
1242 concurrently from another thread while a Fortran formatted I/O
1243 operation is in progress. Also, other threads doing something
1244 dependent on the LC_NUMERIC locale might not work correctly if a
1245 formatted I/O operation is in progress in another thread.
1247 @node Data consistency and durability
1248 @section Data consistency and durability
1249 @cindex consistency, durability
1251 This section contains a brief overview of data and metadata
1252 consistency and durability issues when doing I/O.
1254 With respect to durability, GNU Fortran makes no effort to ensure that
1255 data is committed to stable storage. If this is required, the GNU
1256 Fortran programmer can use the intrinsic @code{FNUM} to retrieve the
1257 low level file descriptor corresponding to an open Fortran unit. Then,
1258 using e.g. the @code{ISO_C_BINDING} feature, one can call the
1259 underlying system call to flush dirty data to stable storage, such as
1260 @code{fsync} on POSIX, @code{_commit} on MingW, or @code{fcntl(fd,
1261 F_FULLSYNC, 0)} on Mac OS X. The following example shows how to call
1265 ! Declare the interface for POSIX fsync function
1267 function fsync (fd) bind(c,name="fsync")
1268 use iso_c_binding, only: c_int
1269 integer(c_int), value :: fd
1270 integer(c_int) :: fsync
1274 ! Variable declaration
1278 open (10,file="foo")
1281 ! Perform I/O on unit 10
1286 ret = fsync(fnum(10))
1288 ! Handle possible error
1289 if (ret /= 0) stop "Error calling FSYNC"
1292 With respect to consistency, for regular files GNU Fortran uses
1293 buffered I/O in order to improve performance. This buffer is flushed
1294 automatically when full and in some other situations, e.g. when
1295 closing a unit. It can also be explicitly flushed with the
1296 @code{FLUSH} statement. Also, the buffering can be turned off with the
1297 @code{GFORTRAN_UNBUFFERED_ALL} and
1298 @code{GFORTRAN_UNBUFFERED_PRECONNECTED} environment variables. Special
1299 files, such as terminals and pipes, are always unbuffered. Sometimes,
1300 however, further things may need to be done in order to allow other
1301 processes to see data that GNU Fortran has written, as follows.
1303 The Windows platform supports a relaxed metadata consistency model,
1304 where file metadata is written to the directory lazily. This means
1305 that, for instance, the @code{dir} command can show a stale size for a
1306 file. One can force a directory metadata update by closing the unit,
1307 or by calling @code{_commit} on the file descriptor. Note, though,
1308 that @code{_commit} will force all dirty data to stable storage, which
1309 is often a very slow operation.
1311 The Network File System (NFS) implements a relaxed consistency model
1312 called open-to-close consistency. Closing a file forces dirty data and
1313 metadata to be flushed to the server, and opening a file forces the
1314 client to contact the server in order to revalidate cached
1315 data. @code{fsync} will also force a flush of dirty data and metadata
1316 to the server. Similar to @code{open} and @code{close}, acquiring and
1317 releasing @code{fcntl} file locks, if the server supports them, will
1318 also force cache validation and flushing dirty data and metadata.
1321 @c ---------------------------------------------------------------------
1323 @c ---------------------------------------------------------------------
1325 @c Maybe this chapter should be merged with the 'Standards' section,
1326 @c whenever that is written :-)
1332 The two sections below detail the extensions to standard Fortran that are
1333 implemented in GNU Fortran, as well as some of the popular or
1334 historically important extensions that are not (or not yet) implemented.
1335 For the latter case, we explain the alternatives available to GNU Fortran
1336 users, including replacement by standard-conforming code or GNU
1340 * Extensions implemented in GNU Fortran::
1341 * Extensions not implemented in GNU Fortran::
1345 @node Extensions implemented in GNU Fortran
1346 @section Extensions implemented in GNU Fortran
1347 @cindex extensions, implemented
1349 GNU Fortran implements a number of extensions over standard
1350 Fortran. This chapter contains information on their syntax and
1351 meaning. There are currently two categories of GNU Fortran
1352 extensions, those that provide functionality beyond that provided
1353 by any standard, and those that are supported by GNU Fortran
1354 purely for backward compatibility with legacy compilers. By default,
1355 @option{-std=gnu} allows the compiler to accept both types of
1356 extensions, but to warn about the use of the latter. Specifying
1357 either @option{-std=f95}, @option{-std=f2003} or @option{-std=f2008}
1358 disables both types of extensions, and @option{-std=legacy} allows both
1362 * Old-style kind specifications::
1363 * Old-style variable initialization::
1364 * Extensions to namelist::
1365 * X format descriptor without count field::
1366 * Commas in FORMAT specifications::
1367 * Missing period in FORMAT specifications::
1369 * @code{Q} exponent-letter::
1370 * BOZ literal constants::
1371 * Real array indices::
1373 * Implicitly convert LOGICAL and INTEGER values::
1374 * Hollerith constants support::
1376 * CONVERT specifier::
1378 * Argument list functions::
1381 @node Old-style kind specifications
1382 @subsection Old-style kind specifications
1383 @cindex kind, old-style
1385 GNU Fortran allows old-style kind specifications in declarations. These
1391 where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
1392 etc.), and where @code{size} is a byte count corresponding to the
1393 storage size of a valid kind for that type. (For @code{COMPLEX}
1394 variables, @code{size} is the total size of the real and imaginary
1395 parts.) The statement then declares @code{x}, @code{y} and @code{z} to
1396 be of type @code{TYPESPEC} with the appropriate kind. This is
1397 equivalent to the standard-conforming declaration
1402 where @code{k} is the kind parameter suitable for the intended precision. As
1403 kind parameters are implementation-dependent, use the @code{KIND},
1404 @code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve
1405 the correct value, for instance @code{REAL*8 x} can be replaced by:
1407 INTEGER, PARAMETER :: dbl = KIND(1.0d0)
1411 @node Old-style variable initialization
1412 @subsection Old-style variable initialization
1414 GNU Fortran allows old-style initialization of variables of the
1418 REAL x(2,2) /3*0.,1./
1420 The syntax for the initializers is as for the @code{DATA} statement, but
1421 unlike in a @code{DATA} statement, an initializer only applies to the
1422 variable immediately preceding the initialization. In other words,
1423 something like @code{INTEGER I,J/2,3/} is not valid. This style of
1424 initialization is only allowed in declarations without double colons
1425 (@code{::}); the double colons were introduced in Fortran 90, which also
1426 introduced a standard syntax for initializing variables in type
1429 Examples of standard-conforming code equivalent to the above example
1433 INTEGER :: i = 1, j = 2
1434 REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x))
1438 DATA i/1/, j/2/, x/3*0.,1./
1441 Note that variables which are explicitly initialized in declarations
1442 or in @code{DATA} statements automatically acquire the @code{SAVE}
1445 @node Extensions to namelist
1446 @subsection Extensions to namelist
1449 GNU Fortran fully supports the Fortran 95 standard for namelist I/O
1450 including array qualifiers, substrings and fully qualified derived types.
1451 The output from a namelist write is compatible with namelist read. The
1452 output has all names in upper case and indentation to column 1 after the
1453 namelist name. Two extensions are permitted:
1455 Old-style use of @samp{$} instead of @samp{&}
1458 X(:)%Y(2) = 1.0 2.0 3.0
1463 It should be noted that the default terminator is @samp{/} rather than
1466 Querying of the namelist when inputting from stdin. After at least
1467 one space, entering @samp{?} sends to stdout the namelist name and the names of
1468 the variables in the namelist:
1479 Entering @samp{=?} outputs the namelist to stdout, as if
1480 @code{WRITE(*,NML = mynml)} had been called:
1485 X(1)%Y= 0.000000 , 1.000000 , 0.000000 ,
1486 X(2)%Y= 0.000000 , 2.000000 , 0.000000 ,
1487 X(3)%Y= 0.000000 , 3.000000 , 0.000000 ,
1491 To aid this dialog, when input is from stdin, errors send their
1492 messages to stderr and execution continues, even if @code{IOSTAT} is set.
1494 @code{PRINT} namelist is permitted. This causes an error if
1495 @option{-std=f95} is used.
1498 REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/)
1501 END PROGRAM test_print
1504 Expanded namelist reads are permitted. This causes an error if
1505 @option{-std=f95} is used. In the following example, the first element
1506 of the array will be given the value 0.00 and the two succeeding
1507 elements will be given the values 1.00 and 2.00.
1510 X(1,1) = 0.00 , 1.00 , 2.00
1514 When writing a namelist, if no @code{DELIM=} is specified, by default a
1515 double quote is used to delimit character strings. If -std=F95, F2003,
1516 or F2008, etc, the delim status is set to 'none'. Defaulting to
1517 quotes ensures that namelists with character strings can be subsequently
1518 read back in accurately.
1520 @node X format descriptor without count field
1521 @subsection @code{X} format descriptor without count field
1523 To support legacy codes, GNU Fortran permits the count field of the
1524 @code{X} edit descriptor in @code{FORMAT} statements to be omitted.
1525 When omitted, the count is implicitly assumed to be one.
1529 10 FORMAT (I1, X, I1)
1532 @node Commas in FORMAT specifications
1533 @subsection Commas in @code{FORMAT} specifications
1535 To support legacy codes, GNU Fortran allows the comma separator
1536 to be omitted immediately before and after character string edit
1537 descriptors in @code{FORMAT} statements.
1541 10 FORMAT ('FOO='I1' BAR='I2)
1545 @node Missing period in FORMAT specifications
1546 @subsection Missing period in @code{FORMAT} specifications
1548 To support legacy codes, GNU Fortran allows missing periods in format
1549 specifications if and only if @option{-std=legacy} is given on the
1550 command line. This is considered non-conforming code and is
1559 @node I/O item lists
1560 @subsection I/O item lists
1561 @cindex I/O item lists
1563 To support legacy codes, GNU Fortran allows the input item list
1564 of the @code{READ} statement, and the output item lists of the
1565 @code{WRITE} and @code{PRINT} statements, to start with a comma.
1567 @node @code{Q} exponent-letter
1568 @subsection @code{Q} exponent-letter
1569 @cindex @code{Q} exponent-letter
1571 GNU Fortran accepts real literal constants with an exponent-letter
1572 of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted
1573 as a @code{REAL(16)} entity on targets that support this type. If
1574 the target does not support @code{REAL(16)} but has a @code{REAL(10)}
1575 type, then the real-literal-constant will be interpreted as a
1576 @code{REAL(10)} entity. In the absence of @code{REAL(16)} and
1577 @code{REAL(10)}, an error will occur.
1579 @node BOZ literal constants
1580 @subsection BOZ literal constants
1581 @cindex BOZ literal constants
1583 Besides decimal constants, Fortran also supports binary (@code{b}),
1584 octal (@code{o}) and hexadecimal (@code{z}) integer constants. The
1585 syntax is: @samp{prefix quote digits quote}, were the prefix is
1586 either @code{b}, @code{o} or @code{z}, quote is either @code{'} or
1587 @code{"} and the digits are for binary @code{0} or @code{1}, for
1588 octal between @code{0} and @code{7}, and for hexadecimal between
1589 @code{0} and @code{F}. (Example: @code{b'01011101'}.)
1591 Up to Fortran 95, BOZ literals were only allowed to initialize
1592 integer variables in DATA statements. Since Fortran 2003 BOZ literals
1593 are also allowed as argument of @code{REAL}, @code{DBLE}, @code{INT}
1594 and @code{CMPLX}; the result is the same as if the integer BOZ
1595 literal had been converted by @code{TRANSFER} to, respectively,
1596 @code{real}, @code{double precision}, @code{integer} or @code{complex}.
1597 As GNU Fortran extension the intrinsic procedures @code{FLOAT},
1598 @code{DFLOAT}, @code{COMPLEX} and @code{DCMPLX} are treated alike.
1600 As an extension, GNU Fortran allows hexadecimal BOZ literal constants to
1601 be specified using the @code{X} prefix, in addition to the standard
1602 @code{Z} prefix. The BOZ literal can also be specified by adding a
1603 suffix to the string, for example, @code{Z'ABC'} and @code{'ABC'Z} are
1606 Furthermore, GNU Fortran allows using BOZ literal constants outside
1607 DATA statements and the four intrinsic functions allowed by Fortran 2003.
1608 In DATA statements, in direct assignments, where the right-hand side
1609 only contains a BOZ literal constant, and for old-style initializers of
1610 the form @code{integer i /o'0173'/}, the constant is transferred
1611 as if @code{TRANSFER} had been used; for @code{COMPLEX} numbers, only
1612 the real part is initialized unless @code{CMPLX} is used. In all other
1613 cases, the BOZ literal constant is converted to an @code{INTEGER} value with
1614 the largest decimal representation. This value is then converted
1615 numerically to the type and kind of the variable in question.
1616 (For instance, @code{real :: r = b'0000001' + 1} initializes @code{r}
1617 with @code{2.0}.) As different compilers implement the extension
1618 differently, one should be careful when doing bitwise initialization
1619 of non-integer variables.
1621 Note that initializing an @code{INTEGER} variable with a statement such
1622 as @code{DATA i/Z'FFFFFFFF'/} will give an integer overflow error rather
1623 than the desired result of @math{-1} when @code{i} is a 32-bit integer
1624 on a system that supports 64-bit integers. The @samp{-fno-range-check}
1625 option can be used as a workaround for legacy code that initializes
1626 integers in this manner.
1628 @node Real array indices
1629 @subsection Real array indices
1630 @cindex array, indices of type real
1632 As an extension, GNU Fortran allows the use of @code{REAL} expressions
1633 or variables as array indices.
1635 @node Unary operators
1636 @subsection Unary operators
1637 @cindex operators, unary
1639 As an extension, GNU Fortran allows unary plus and unary minus operators
1640 to appear as the second operand of binary arithmetic operators without
1641 the need for parenthesis.
1647 @node Implicitly convert LOGICAL and INTEGER values
1648 @subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values
1649 @cindex conversion, to integer
1650 @cindex conversion, to logical
1652 As an extension for backwards compatibility with other compilers, GNU
1653 Fortran allows the implicit conversion of @code{LOGICAL} values to
1654 @code{INTEGER} values and vice versa. When converting from a
1655 @code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as
1656 zero, and @code{.TRUE.} is interpreted as one. When converting from
1657 @code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as
1658 @code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}.
1669 However, there is no implicit conversion of @code{INTEGER} values in
1670 @code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values
1673 @node Hollerith constants support
1674 @subsection Hollerith constants support
1675 @cindex Hollerith constants
1677 GNU Fortran supports Hollerith constants in assignments, function
1678 arguments, and @code{DATA} and @code{ASSIGN} statements. A Hollerith
1679 constant is written as a string of characters preceded by an integer
1680 constant indicating the character count, and the letter @code{H} or
1681 @code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER},
1682 @code{REAL}, or @code{complex}) or @code{LOGICAL} variable. The
1683 constant will be padded or truncated to fit the size of the variable in
1686 Examples of valid uses of Hollerith constants:
1689 data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/
1690 x(1) = 16HABCDEFGHIJKLMNOP
1694 Invalid Hollerith constants examples:
1697 a = 8H12345678 ! Valid, but the Hollerith constant will be truncated.
1698 a = 0H ! At least one character is needed.
1701 In general, Hollerith constants were used to provide a rudimentary
1702 facility for handling character strings in early Fortran compilers,
1703 prior to the introduction of @code{CHARACTER} variables in Fortran 77;
1704 in those cases, the standard-compliant equivalent is to convert the
1705 program to use proper character strings. On occasion, there may be a
1706 case where the intent is specifically to initialize a numeric variable
1707 with a given byte sequence. In these cases, the same result can be
1708 obtained by using the @code{TRANSFER} statement, as in this example.
1710 INTEGER(KIND=4) :: a
1711 a = TRANSFER ("abcd", a) ! equivalent to: a = 4Habcd
1716 @subsection Cray pointers
1717 @cindex pointer, Cray
1719 Cray pointers are part of a non-standard extension that provides a
1720 C-like pointer in Fortran. This is accomplished through a pair of
1721 variables: an integer "pointer" that holds a memory address, and a
1722 "pointee" that is used to dereference the pointer.
1724 Pointer/pointee pairs are declared in statements of the form:
1726 pointer ( <pointer> , <pointee> )
1730 pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ...
1732 The pointer is an integer that is intended to hold a memory address.
1733 The pointee may be an array or scalar. A pointee can be an assumed
1734 size array---that is, the last dimension may be left unspecified by
1735 using a @code{*} in place of a value---but a pointee cannot be an
1736 assumed shape array. No space is allocated for the pointee.
1738 The pointee may have its type declared before or after the pointer
1739 statement, and its array specification (if any) may be declared
1740 before, during, or after the pointer statement. The pointer may be
1741 declared as an integer prior to the pointer statement. However, some
1742 machines have default integer sizes that are different than the size
1743 of a pointer, and so the following code is not portable:
1748 If a pointer is declared with a kind that is too small, the compiler
1749 will issue a warning; the resulting binary will probably not work
1750 correctly, because the memory addresses stored in the pointers may be
1751 truncated. It is safer to omit the first line of the above example;
1752 if explicit declaration of ipt's type is omitted, then the compiler
1753 will ensure that ipt is an integer variable large enough to hold a
1756 Pointer arithmetic is valid with Cray pointers, but it is not the same
1757 as C pointer arithmetic. Cray pointers are just ordinary integers, so
1758 the user is responsible for determining how many bytes to add to a
1759 pointer in order to increment it. Consider the following example:
1763 pointer (ipt, pointee)
1767 The last statement does not set @code{ipt} to the address of
1768 @code{target(1)}, as it would in C pointer arithmetic. Adding @code{1}
1769 to @code{ipt} just adds one byte to the address stored in @code{ipt}.
1771 Any expression involving the pointee will be translated to use the
1772 value stored in the pointer as the base address.
1774 To get the address of elements, this extension provides an intrinsic
1775 function @code{LOC()}. The @code{LOC()} function is equivalent to the
1776 @code{&} operator in C, except the address is cast to an integer type:
1779 pointer(ipt, arpte(10))
1781 ipt = loc(ar) ! Makes arpte is an alias for ar
1782 arpte(1) = 1.0 ! Sets ar(1) to 1.0
1784 The pointer can also be set by a call to the @code{MALLOC} intrinsic
1787 Cray pointees often are used to alias an existing variable. For
1795 As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for
1796 @code{target}. The optimizer, however, will not detect this aliasing, so
1797 it is unsafe to use @code{iarr} and @code{target} simultaneously. Using
1798 a pointee in any way that violates the Fortran aliasing rules or
1799 assumptions is illegal. It is the user's responsibility to avoid doing
1800 this; the compiler works under the assumption that no such aliasing
1803 Cray pointers will work correctly when there is no aliasing (i.e., when
1804 they are used to access a dynamically allocated block of memory), and
1805 also in any routine where a pointee is used, but any variable with which
1806 it shares storage is not used. Code that violates these rules may not
1807 run as the user intends. This is not a bug in the optimizer; any code
1808 that violates the aliasing rules is illegal. (Note that this is not
1809 unique to GNU Fortran; any Fortran compiler that supports Cray pointers
1810 will ``incorrectly'' optimize code with illegal aliasing.)
1812 There are a number of restrictions on the attributes that can be applied
1813 to Cray pointers and pointees. Pointees may not have the
1814 @code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY},
1815 @code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers
1816 may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET},
1817 @code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor
1818 may they be function results. Pointees may not occur in more than one
1819 pointer statement. A pointee cannot be a pointer. Pointees cannot occur
1820 in equivalence, common, or data statements.
1822 A Cray pointer may also point to a function or a subroutine. For
1823 example, the following excerpt is valid:
1827 pointer (subptr,subpte)
1837 A pointer may be modified during the course of a program, and this
1838 will change the location to which the pointee refers. However, when
1839 pointees are passed as arguments, they are treated as ordinary
1840 variables in the invoked function. Subsequent changes to the pointer
1841 will not change the base address of the array that was passed.
1843 @node CONVERT specifier
1844 @subsection @code{CONVERT} specifier
1845 @cindex @code{CONVERT} specifier
1847 GNU Fortran allows the conversion of unformatted data between little-
1848 and big-endian representation to facilitate moving of data
1849 between different systems. The conversion can be indicated with
1850 the @code{CONVERT} specifier on the @code{OPEN} statement.
1851 @xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying
1852 the data format via an environment variable.
1854 Valid values for @code{CONVERT} are:
1856 @item @code{CONVERT='NATIVE'} Use the native format. This is the default.
1857 @item @code{CONVERT='SWAP'} Swap between little- and big-endian.
1858 @item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation
1859 for unformatted files.
1860 @item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for
1864 Using the option could look like this:
1866 open(file='big.dat',form='unformatted',access='sequential', &
1867 convert='big_endian')
1870 The value of the conversion can be queried by using
1871 @code{INQUIRE(CONVERT=ch)}. The values returned are
1872 @code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}.
1874 @code{CONVERT} works between big- and little-endian for
1875 @code{INTEGER} values of all supported kinds and for @code{REAL}
1876 on IEEE systems of kinds 4 and 8. Conversion between different
1877 ``extended double'' types on different architectures such as
1878 m68k and x86_64, which GNU Fortran
1879 supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will
1882 @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
1883 environment variable will override the CONVERT specifier in the
1884 open statement}. This is to give control over data formats to
1885 users who do not have the source code of their program available.
1887 Using anything but the native representation for unformatted data
1888 carries a significant speed overhead. If speed in this area matters
1889 to you, it is best if you use this only for data that needs to be
1896 OpenMP (Open Multi-Processing) is an application programming
1897 interface (API) that supports multi-platform shared memory
1898 multiprocessing programming in C/C++ and Fortran on many
1899 architectures, including Unix and Microsoft Windows platforms.
1900 It consists of a set of compiler directives, library routines,
1901 and environment variables that influence run-time behavior.
1903 GNU Fortran strives to be compatible to the
1904 @uref{http://openmp.org/wp/openmp-specifications/,
1905 OpenMP Application Program Interface v4.0}.
1907 To enable the processing of the OpenMP directive @code{!$omp} in
1908 free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp}
1909 directives in fixed form; the @code{!$} conditional compilation sentinels
1910 in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels
1911 in fixed form, @command{gfortran} needs to be invoked with the
1912 @option{-fopenmp}. This also arranges for automatic linking of the
1913 GNU OpenMP runtime library @ref{Top,,libgomp,libgomp,GNU OpenMP
1916 The OpenMP Fortran runtime library routines are provided both in a
1917 form of a Fortran 90 module named @code{omp_lib} and in a form of
1918 a Fortran @code{include} file named @file{omp_lib.h}.
1920 An example of a parallelized loop taken from Appendix A.1 of
1921 the OpenMP Application Program Interface v2.5:
1923 SUBROUTINE A1(N, A, B)
1926 !$OMP PARALLEL DO !I is private by default
1928 B(I) = (A(I) + A(I-1)) / 2.0
1930 !$OMP END PARALLEL DO
1937 @option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays
1938 will be allocated on the stack. When porting existing code to OpenMP,
1939 this may lead to surprising results, especially to segmentation faults
1940 if the stacksize is limited.
1943 On glibc-based systems, OpenMP enabled applications cannot be statically
1944 linked due to limitations of the underlying pthreads-implementation. It
1945 might be possible to get a working solution if
1946 @command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added
1947 to the command line. However, this is not supported by @command{gcc} and
1948 thus not recommended.
1951 @node Argument list functions
1952 @subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC}
1953 @cindex argument list functions
1958 GNU Fortran supports argument list functions @code{%VAL}, @code{%REF}
1959 and @code{%LOC} statements, for backward compatibility with g77.
1960 It is recommended that these should be used only for code that is
1961 accessing facilities outside of GNU Fortran, such as operating system
1962 or windowing facilities. It is best to constrain such uses to isolated
1963 portions of a program--portions that deal specifically and exclusively
1964 with low-level, system-dependent facilities. Such portions might well
1965 provide a portable interface for use by the program as a whole, but are
1966 themselves not portable, and should be thoroughly tested each time they
1967 are rebuilt using a new compiler or version of a compiler.
1969 @code{%VAL} passes a scalar argument by value, @code{%REF} passes it by
1970 reference and @code{%LOC} passes its memory location. Since gfortran
1971 already passes scalar arguments by reference, @code{%REF} is in effect
1972 a do-nothing. @code{%LOC} has the same effect as a Fortran pointer.
1974 An example of passing an argument by value to a C subroutine foo.:
1977 C prototype void foo_ (float x);
1986 For details refer to the g77 manual
1987 @uref{https://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}.
1989 Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the
1990 GNU Fortran testsuite are worth a look.
1993 @node Extensions not implemented in GNU Fortran
1994 @section Extensions not implemented in GNU Fortran
1995 @cindex extensions, not implemented
1997 The long history of the Fortran language, its wide use and broad
1998 userbase, the large number of different compiler vendors and the lack of
1999 some features crucial to users in the first standards have lead to the
2000 existence of a number of important extensions to the language. While
2001 some of the most useful or popular extensions are supported by the GNU
2002 Fortran compiler, not all existing extensions are supported. This section
2003 aims at listing these extensions and offering advice on how best make
2004 code that uses them running with the GNU Fortran compiler.
2006 @c More can be found here:
2007 @c -- https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html
2008 @c -- the list of Fortran and libgfortran bugs closed as WONTFIX:
2009 @c http://tinyurl.com/2u4h5y
2012 * STRUCTURE and RECORD::
2013 @c * UNION and MAP::
2014 * ENCODE and DECODE statements::
2015 * Variable FORMAT expressions::
2016 @c * Q edit descriptor::
2017 @c * AUTOMATIC statement::
2018 @c * TYPE and ACCEPT I/O Statements::
2019 @c * .XOR. operator::
2020 @c * CARRIAGECONTROL, DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers::
2021 @c * Omitted arguments in procedure call::
2022 * Alternate complex function syntax::
2023 * Volatile COMMON blocks::
2027 @node STRUCTURE and RECORD
2028 @subsection @code{STRUCTURE} and @code{RECORD}
2029 @cindex @code{STRUCTURE}
2030 @cindex @code{RECORD}
2032 Record structures are a pre-Fortran-90 vendor extension to create
2033 user-defined aggregate data types. GNU Fortran does not support
2034 record structures, only Fortran 90's ``derived types'', which have
2037 In many cases, record structures can easily be converted to derived types.
2038 To convert, replace @code{STRUCTURE /}@var{structure-name}@code{/}
2039 by @code{TYPE} @var{type-name}. Additionally, replace
2040 @code{RECORD /}@var{structure-name}@code{/} by
2041 @code{TYPE(}@var{type-name}@code{)}. Finally, in the component access,
2042 replace the period (@code{.}) by the percent sign (@code{%}).
2044 Here is an example of code using the non portable record structure syntax:
2047 ! Declaring a structure named ``item'' and containing three fields:
2048 ! an integer ID, an description string and a floating-point price.
2051 CHARACTER(LEN=200) description
2055 ! Define two variables, an single record of type ``item''
2056 ! named ``pear'', and an array of items named ``store_catalog''
2057 RECORD /item/ pear, store_catalog(100)
2059 ! We can directly access the fields of both variables
2061 pear.description = "juicy D'Anjou pear"
2063 store_catalog(7).id = 7831
2064 store_catalog(7).description = "milk bottle"
2065 store_catalog(7).price = 1.2
2067 ! We can also manipulate the whole structure
2068 store_catalog(12) = pear
2069 print *, store_catalog(12)
2073 This code can easily be rewritten in the Fortran 90 syntax as following:
2076 ! ``STRUCTURE /name/ ... END STRUCTURE'' becomes
2077 ! ``TYPE name ... END TYPE''
2080 CHARACTER(LEN=200) description
2084 ! ``RECORD /name/ variable'' becomes ``TYPE(name) variable''
2085 TYPE(item) pear, store_catalog(100)
2087 ! Instead of using a dot (.) to access fields of a record, the
2088 ! standard syntax uses a percent sign (%)
2090 pear%description = "juicy D'Anjou pear"
2092 store_catalog(7)%id = 7831
2093 store_catalog(7)%description = "milk bottle"
2094 store_catalog(7)%price = 1.2
2096 ! Assignments of a whole variable do not change
2097 store_catalog(12) = pear
2098 print *, store_catalog(12)
2102 @c @node UNION and MAP
2103 @c @subsection @code{UNION} and @code{MAP}
2104 @c @cindex @code{UNION}
2105 @c @cindex @code{MAP}
2107 @c For help writing this one, see
2108 @c http://www.eng.umd.edu/~nsw/ench250/fortran1.htm#UNION and
2109 @c http://www.tacc.utexas.edu/services/userguides/pgi/pgiws_ug/pgi32u06.htm
2112 @node ENCODE and DECODE statements
2113 @subsection @code{ENCODE} and @code{DECODE} statements
2114 @cindex @code{ENCODE}
2115 @cindex @code{DECODE}
2117 GNU Fortran does not support the @code{ENCODE} and @code{DECODE}
2118 statements. These statements are best replaced by @code{READ} and
2119 @code{WRITE} statements involving internal files (@code{CHARACTER}
2120 variables and arrays), which have been part of the Fortran standard since
2121 Fortran 77. For example, replace a code fragment like
2126 c ... Code that sets LINE
2127 DECODE (80, 9000, LINE) A, B, C
2128 9000 FORMAT (1X, 3(F10.5))
2135 CHARACTER(LEN=80) LINE
2137 c ... Code that sets LINE
2138 READ (UNIT=LINE, FMT=9000) A, B, C
2139 9000 FORMAT (1X, 3(F10.5))
2142 Similarly, replace a code fragment like
2147 c ... Code that sets A, B and C
2148 ENCODE (80, 9000, LINE) A, B, C
2149 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2156 CHARACTER(LEN=80) LINE
2158 c ... Code that sets A, B and C
2159 WRITE (UNIT=LINE, FMT=9000) A, B, C
2160 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
2164 @node Variable FORMAT expressions
2165 @subsection Variable @code{FORMAT} expressions
2166 @cindex @code{FORMAT}
2168 A variable @code{FORMAT} expression is format statement which includes
2169 angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU
2170 Fortran does not support this legacy extension. The effect of variable
2171 format expressions can be reproduced by using the more powerful (and
2172 standard) combination of internal output and string formats. For example,
2173 replace a code fragment like this:
2184 c Variable declaration
2185 CHARACTER(LEN=20) FMT
2187 c Other code here...
2189 WRITE(FMT,'("(I", I0, ")")') N+1
2197 c Variable declaration
2198 CHARACTER(LEN=20) FMT
2200 c Other code here...
2203 WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1
2207 @node Alternate complex function syntax
2208 @subsection Alternate complex function syntax
2209 @cindex Complex function
2211 Some Fortran compilers, including @command{g77}, let the user declare
2212 complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as
2213 well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy
2214 extensions. @command{gfortran} accepts the latter form, which is more
2215 common, but not the former.
2218 @node Volatile COMMON blocks
2219 @subsection Volatile @code{COMMON} blocks
2220 @cindex @code{VOLATILE}
2221 @cindex @code{COMMON}
2223 Some Fortran compilers, including @command{g77}, let the user declare
2224 @code{COMMON} with the @code{VOLATILE} attribute. This is
2225 invalid standard Fortran syntax and is not supported by
2226 @command{gfortran}. Note that @command{gfortran} accepts
2227 @code{VOLATILE} variables in @code{COMMON} blocks since revision 4.3.
2231 @c ---------------------------------------------------------------------
2232 @c Mixed-Language Programming
2233 @c ---------------------------------------------------------------------
2235 @node Mixed-Language Programming
2236 @chapter Mixed-Language Programming
2237 @cindex Interoperability
2238 @cindex Mixed-language programming
2241 * Interoperability with C::
2242 * GNU Fortran Compiler Directives::
2243 * Non-Fortran Main Program::
2244 * Naming and argument-passing conventions::
2247 This chapter is about mixed-language interoperability, but also applies
2248 if one links Fortran code compiled by different compilers. In most cases,
2249 use of the C Binding features of the Fortran 2003 standard is sufficient,
2250 and their use is highly recommended.
2253 @node Interoperability with C
2254 @section Interoperability with C
2258 * Derived Types and struct::
2259 * Interoperable Global Variables::
2260 * Interoperable Subroutines and Functions::
2261 * Working with Pointers::
2262 * Further Interoperability of Fortran with C::
2265 Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a
2266 standardized way to generate procedure and derived-type
2267 declarations and global variables which are interoperable with C
2268 (ISO/IEC 9899:1999). The @code{bind(C)} attribute has been added
2269 to inform the compiler that a symbol shall be interoperable with C;
2270 also, some constraints are added. Note, however, that not
2271 all C features have a Fortran equivalent or vice versa. For instance,
2272 neither C's unsigned integers nor C's functions with variable number
2273 of arguments have an equivalent in Fortran.
2275 Note that array dimensions are reversely ordered in C and that arrays in
2276 C always start with index 0 while in Fortran they start by default with
2277 1. Thus, an array declaration @code{A(n,m)} in Fortran matches
2278 @code{A[m][n]} in C and accessing the element @code{A(i,j)} matches
2279 @code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]};
2280 assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}).
2282 @node Intrinsic Types
2283 @subsection Intrinsic Types
2285 In order to ensure that exactly the same variable type and kind is used
2286 in C and Fortran, the named constants shall be used which are defined in the
2287 @code{ISO_C_BINDING} intrinsic module. That module contains named constants
2288 for kind parameters and character named constants for the escape sequences
2289 in C. For a list of the constants, see @ref{ISO_C_BINDING}.
2291 For logical types, please note that the Fortran standard only guarantees
2292 interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
2293 logicals and C99 defines that @code{true} has the value 1 and @code{false}
2294 the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL}
2295 (with any kind parameter) gives an undefined result. (Passing other integer
2296 values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the
2297 integer is explicitly or implicitly casted to @code{_Bool}.)
2301 @node Derived Types and struct
2302 @subsection Derived Types and struct
2304 For compatibility of derived types with @code{struct}, one needs to use
2305 the @code{BIND(C)} attribute in the type declaration. For instance, the
2306 following type declaration
2310 TYPE, BIND(C) :: myType
2311 INTEGER(C_INT) :: i1, i2
2312 INTEGER(C_SIGNED_CHAR) :: i3
2313 REAL(C_DOUBLE) :: d1
2314 COMPLEX(C_FLOAT_COMPLEX) :: c1
2315 CHARACTER(KIND=C_CHAR) :: str(5)
2319 matches the following @code{struct} declaration in C
2324 /* Note: "char" might be signed or unsigned. */
2332 Derived types with the C binding attribute shall not have the @code{sequence}
2333 attribute, type parameters, the @code{extends} attribute, nor type-bound
2334 procedures. Every component must be of interoperable type and kind and may not
2335 have the @code{pointer} or @code{allocatable} attribute. The names of the
2336 components are irrelevant for interoperability.
2338 As there exist no direct Fortran equivalents, neither unions nor structs
2339 with bit field or variable-length array members are interoperable.
2341 @node Interoperable Global Variables
2342 @subsection Interoperable Global Variables
2344 Variables can be made accessible from C using the C binding attribute,
2345 optionally together with specifying a binding name. Those variables
2346 have to be declared in the declaration part of a @code{MODULE},
2347 be of interoperable type, and have neither the @code{pointer} nor
2348 the @code{allocatable} attribute.
2354 integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag
2355 type(myType), bind(C) :: tp
2359 Here, @code{_MyProject_flags} is the case-sensitive name of the variable
2360 as seen from C programs while @code{global_flag} is the case-insensitive
2361 name as seen from Fortran. If no binding name is specified, as for
2362 @var{tp}, the C binding name is the (lowercase) Fortran binding name.
2363 If a binding name is specified, only a single variable may be after the
2364 double colon. Note of warning: You cannot use a global variable to
2365 access @var{errno} of the C library as the C standard allows it to be
2366 a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead.
2368 @node Interoperable Subroutines and Functions
2369 @subsection Interoperable Subroutines and Functions
2371 Subroutines and functions have to have the @code{BIND(C)} attribute to
2372 be compatible with C. The dummy argument declaration is relatively
2373 straightforward. However, one needs to be careful because C uses
2374 call-by-value by default while Fortran behaves usually similar to
2375 call-by-reference. Furthermore, strings and pointers are handled
2376 differently. Note that in Fortran 2003 and 2008 only explicit size
2377 and assumed-size arrays are supported but not assumed-shape or
2378 deferred-shape (i.e. allocatable or pointer) arrays. However, those
2379 are allowed since the Technical Specification 29113, see
2380 @ref{Further Interoperability of Fortran with C}
2382 To pass a variable by value, use the @code{VALUE} attribute.
2383 Thus, the following C prototype
2386 @code{int func(int i, int *j)}
2389 matches the Fortran declaration
2392 integer(c_int) function func(i,j)
2393 use iso_c_binding, only: c_int
2394 integer(c_int), VALUE :: i
2398 Note that pointer arguments also frequently need the @code{VALUE} attribute,
2399 see @ref{Working with Pointers}.
2401 Strings are handled quite differently in C and Fortran. In C a string
2402 is a @code{NUL}-terminated array of characters while in Fortran each string
2403 has a length associated with it and is thus not terminated (by e.g.
2404 @code{NUL}). For example, if one wants to use the following C function,
2408 void print_C(char *string) /* equivalent: char string[] */
2410 printf("%s\n", string);
2414 to print ``Hello World'' from Fortran, one can call it using
2417 use iso_c_binding, only: C_CHAR, C_NULL_CHAR
2419 subroutine print_c(string) bind(C, name="print_C")
2420 use iso_c_binding, only: c_char
2421 character(kind=c_char) :: string(*)
2422 end subroutine print_c
2424 call print_c(C_CHAR_"Hello World"//C_NULL_CHAR)
2427 As the example shows, one needs to ensure that the
2428 string is @code{NUL} terminated. Additionally, the dummy argument
2429 @var{string} of @code{print_C} is a length-one assumed-size
2430 array; using @code{character(len=*)} is not allowed. The example
2431 above uses @code{c_char_"Hello World"} to ensure the string
2432 literal has the right type; typically the default character
2433 kind and @code{c_char} are the same and thus @code{"Hello World"}
2434 is equivalent. However, the standard does not guarantee this.
2436 The use of strings is now further illustrated using the C library
2437 function @code{strncpy}, whose prototype is
2440 char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
2443 The function @code{strncpy} copies at most @var{n} characters from
2444 string @var{s2} to @var{s1} and returns @var{s1}. In the following
2445 example, we ignore the return value:
2450 character(len=30) :: str,str2
2452 ! Ignore the return value of strncpy -> subroutine
2453 ! "restrict" is always assumed if we do not pass a pointer
2454 subroutine strncpy(dest, src, n) bind(C)
2456 character(kind=c_char), intent(out) :: dest(*)
2457 character(kind=c_char), intent(in) :: src(*)
2458 integer(c_size_t), value, intent(in) :: n
2459 end subroutine strncpy
2461 str = repeat('X',30) ! Initialize whole string with 'X'
2462 call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, &
2463 len(c_char_"Hello World",kind=c_size_t))
2464 print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX"
2468 The intrinsic procedures are described in @ref{Intrinsic Procedures}.
2470 @node Working with Pointers
2471 @subsection Working with Pointers
2473 C pointers are represented in Fortran via the special opaque derived type
2474 @code{type(c_ptr)} (with private components). Thus one needs to
2475 use intrinsic conversion procedures to convert from or to C pointers.
2477 For some applications, using an assumed type (@code{TYPE(*)}) can be an
2478 alternative to a C pointer; see
2479 @ref{Further Interoperability of Fortran with C}.
2485 type(c_ptr) :: cptr1, cptr2
2486 integer, target :: array(7), scalar
2487 integer, pointer :: pa(:), ps
2488 cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the
2489 ! array is contiguous if required by the C
2491 cptr2 = c_loc(scalar)
2492 call c_f_pointer(cptr2, ps)
2493 call c_f_pointer(cptr2, pa, shape=[7])
2496 When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument
2499 If a pointer is a dummy-argument of an interoperable procedure, it usually
2500 has to be declared using the @code{VALUE} attribute. @code{void*}
2501 matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone
2502 matches @code{void**}.
2504 Procedure pointers are handled analogously to pointers; the C type is
2505 @code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are
2506 @code{C_F_PROCPOINTER} and @code{C_FUNLOC}.
2508 Let us consider two examples of actually passing a procedure pointer from
2509 C to Fortran and vice versa. Note that these examples are also very
2510 similar to passing ordinary pointers between both languages. First,
2511 consider this code in C:
2514 /* Procedure implemented in Fortran. */
2515 void get_values (void (*)(double));
2517 /* Call-back routine we want called from Fortran. */
2521 printf ("Number is %f.\n", x);
2524 /* Call Fortran routine and pass call-back to it. */
2528 get_values (&print_it);
2532 A matching implementation for @code{get_values} in Fortran, that correctly
2533 receives the procedure pointer from C and is able to call it, is given
2534 in the following @code{MODULE}:
2540 ! Define interface of call-back routine.
2542 SUBROUTINE callback (x)
2543 USE, INTRINSIC :: ISO_C_BINDING
2544 REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x
2545 END SUBROUTINE callback
2550 ! Define C-bound procedure.
2551 SUBROUTINE get_values (cproc) BIND(C)
2552 USE, INTRINSIC :: ISO_C_BINDING
2553 TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc
2555 PROCEDURE(callback), POINTER :: proc
2557 ! Convert C to Fortran procedure pointer.
2558 CALL C_F_PROCPOINTER (cproc, proc)
2561 CALL proc (1.0_C_DOUBLE)
2562 CALL proc (-42.0_C_DOUBLE)
2563 CALL proc (18.12_C_DOUBLE)
2564 END SUBROUTINE get_values
2569 Next, we want to call a C routine that expects a procedure pointer argument
2570 and pass it a Fortran procedure (which clearly must be interoperable!).
2571 Again, the C function may be:
2575 call_it (int (*func)(int), int arg)
2581 It can be used as in the following Fortran code:
2585 USE, INTRINSIC :: ISO_C_BINDING
2588 ! Define interface of C function.
2590 INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C)
2591 USE, INTRINSIC :: ISO_C_BINDING
2592 TYPE(C_FUNPTR), INTENT(IN), VALUE :: func
2593 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
2594 END FUNCTION call_it
2599 ! Define procedure passed to C function.
2600 ! It must be interoperable!
2601 INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C)
2602 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg
2603 double_it = arg + arg
2604 END FUNCTION double_it
2607 SUBROUTINE foobar ()
2608 TYPE(C_FUNPTR) :: cproc
2609 INTEGER(KIND=C_INT) :: i
2611 ! Get C procedure pointer.
2612 cproc = C_FUNLOC (double_it)
2615 DO i = 1_C_INT, 10_C_INT
2616 PRINT *, call_it (cproc, i)
2618 END SUBROUTINE foobar
2623 @node Further Interoperability of Fortran with C
2624 @subsection Further Interoperability of Fortran with C
2626 The Technical Specification ISO/IEC TS 29113:2012 on further
2627 interoperability of Fortran with C extends the interoperability support
2628 of Fortran 2003 and Fortran 2008. Besides removing some restrictions
2629 and constraints, it adds assumed-type (@code{TYPE(*)}) and assumed-rank
2630 (@code{dimension}) variables and allows for interoperability of
2631 assumed-shape, assumed-rank and deferred-shape arrays, including
2632 allocatables and pointers.
2634 Note: Currently, GNU Fortran does not support the array descriptor
2635 (dope vector) as specified in the Technical Specification, but uses
2636 an array descriptor with different fields. The Chasm Language
2637 Interoperability Tools, @url{http://chasm-interop.sourceforge.net/},
2638 provide an interface to GNU Fortran's array descriptor.
2640 The Technical Specification adds the following new features, which
2641 are supported by GNU Fortran:
2645 @item The @code{ASYNCHRONOUS} attribute has been clarified and
2646 extended to allow its use with asynchronous communication in
2647 user-provided libraries such as in implementations of the
2648 Message Passing Interface specification.
2650 @item Many constraints have been relaxed, in particular for
2651 the @code{C_LOC} and @code{C_F_POINTER} intrinsics.
2653 @item The @code{OPTIONAL} attribute is now allowed for dummy
2654 arguments; an absent argument matches a @code{NULL} pointer.
2656 @item Assumed types (@code{TYPE(*)}) have been added, which may
2657 only be used for dummy arguments. They are unlimited polymorphic
2658 but contrary to @code{CLASS(*)} they do not contain any type
2659 information, similar to C's @code{void *} pointers. Expressions
2660 of any type and kind can be passed; thus, it can be used as
2661 replacement for @code{TYPE(C_PTR)}, avoiding the use of
2662 @code{C_LOC} in the caller.
2664 Note, however, that @code{TYPE(*)} only accepts scalar arguments,
2665 unless the @code{DIMENSION} is explicitly specified. As
2666 @code{DIMENSION(*)} only supports array (including array elements) but
2667 no scalars, it is not a full replacement for @code{C_LOC}. On the
2668 other hand, assumed-type assumed-rank dummy arguments
2669 (@code{TYPE(*), DIMENSION(..)}) allow for both scalars and arrays, but
2670 require special code on the callee side to handle the array descriptor.
2672 @item Assumed-rank arrays (@code{DIMENSION(..)}) as dummy argument
2673 allow that scalars and arrays of any rank can be passed as actual
2674 argument. As the Technical Specification does not provide for direct
2675 means to operate with them, they have to be used either from the C side
2676 or be converted using @code{C_LOC} and @code{C_F_POINTER} to scalars
2677 or arrays of a specific rank. The rank can be determined using the
2678 @code{RANK} intrinisic.
2682 Currently unimplemented:
2686 @item GNU Fortran always uses an array descriptor, which does not
2687 match the one of the Technical Specification. The
2688 @code{ISO_Fortran_binding.h} header file and the C functions it
2689 specifies are not available.
2691 @item Using assumed-shape, assumed-rank and deferred-shape arrays in
2692 @code{BIND(C)} procedures is not fully supported. In particular,
2693 C interoperable strings of other length than one are not supported
2694 as this requires the new array descriptor.
2698 @node GNU Fortran Compiler Directives
2699 @section GNU Fortran Compiler Directives
2701 The Fortran standard describes how a conforming program shall
2702 behave; however, the exact implementation is not standardized. In order
2703 to allow the user to choose specific implementation details, compiler
2704 directives can be used to set attributes of variables and procedures
2705 which are not part of the standard. Whether a given attribute is
2706 supported and its exact effects depend on both the operating system and
2707 on the processor; see
2708 @ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)}
2711 For procedures and procedure pointers, the following attributes can
2712 be used to change the calling convention:
2715 @item @code{CDECL} -- standard C calling convention
2716 @item @code{STDCALL} -- convention where the called procedure pops the stack
2717 @item @code{FASTCALL} -- part of the arguments are passed via registers
2718 instead using the stack
2721 Besides changing the calling convention, the attributes also influence
2722 the decoration of the symbol name, e.g., by a leading underscore or by
2723 a trailing at-sign followed by the number of bytes on the stack. When
2724 assigning a procedure to a procedure pointer, both should use the same
2727 On some systems, procedures and global variables (module variables and
2728 @code{COMMON} blocks) need special handling to be accessible when they
2729 are in a shared library. The following attributes are available:
2732 @item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL
2733 @item @code{DLLIMPORT} -- reference the function or variable using a
2737 For dummy arguments, the @code{NO_ARG_CHECK} attribute can be used; in
2738 other compilers, it is also known as @code{IGNORE_TKR}. For dummy arguments
2739 with this attribute actual arguments of any type and kind (similar to
2740 @code{TYPE(*)}), scalars and arrays of any rank (no equivalent
2741 in Fortran standard) are accepted. As with @code{TYPE(*)}, the argument
2742 is unlimited polymorphic and no type information is available.
2743 Additionally, the argument may only be passed to dummy arguments
2744 with the @code{NO_ARG_CHECK} attribute and as argument to the
2745 @code{PRESENT} intrinsic function and to @code{C_LOC} of the
2746 @code{ISO_C_BINDING} module.
2748 Variables with @code{NO_ARG_CHECK} attribute shall be of assumed-type
2749 (@code{TYPE(*)}; recommended) or of type @code{INTEGER}, @code{LOGICAL},
2750 @code{REAL} or @code{COMPLEX}. They shall not have the @code{ALLOCATE},
2751 @code{CODIMENSION}, @code{INTENT(OUT)}, @code{POINTER} or @code{VALUE}
2752 attribute; furthermore, they shall be either scalar or of assumed-size
2753 (@code{dimension(*)}). As @code{TYPE(*)}, the @code{NO_ARG_CHECK} attribute
2754 requires an explicit interface.
2757 @item @code{NO_ARG_CHECK} -- disable the type, kind and rank checking
2761 The attributes are specified using the syntax
2763 @code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list}
2765 where in free-form source code only whitespace is allowed before @code{!GCC$}
2766 and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall
2767 start in the first column.
2769 For procedures, the compiler directives shall be placed into the body
2770 of the procedure; for variables and procedure pointers, they shall be in
2771 the same declaration part as the variable or procedure pointer.
2775 @node Non-Fortran Main Program
2776 @section Non-Fortran Main Program
2779 * _gfortran_set_args:: Save command-line arguments
2780 * _gfortran_set_options:: Set library option flags
2781 * _gfortran_set_convert:: Set endian conversion
2782 * _gfortran_set_record_marker:: Set length of record markers
2783 * _gfortran_set_fpe:: Set when a Floating Point Exception should be raised
2784 * _gfortran_set_max_subrecord_length:: Set subrecord length
2787 Even if you are doing mixed-language programming, it is very
2788 likely that you do not need to know or use the information in this
2789 section. Since it is about the internal structure of GNU Fortran,
2790 it may also change in GCC minor releases.
2792 When you compile a @code{PROGRAM} with GNU Fortran, a function
2793 with the name @code{main} (in the symbol table of the object file)
2794 is generated, which initializes the libgfortran library and then
2795 calls the actual program which uses the name @code{MAIN__}, for
2796 historic reasons. If you link GNU Fortran compiled procedures
2797 to, e.g., a C or C++ program or to a Fortran program compiled by
2798 a different compiler, the libgfortran library is not initialized
2799 and thus a few intrinsic procedures do not work properly, e.g.
2800 those for obtaining the command-line arguments.
2802 Therefore, if your @code{PROGRAM} is not compiled with
2803 GNU Fortran and the GNU Fortran compiled procedures require
2804 intrinsics relying on the library initialization, you need to
2805 initialize the library yourself. Using the default options,
2806 gfortran calls @code{_gfortran_set_args} and
2807 @code{_gfortran_set_options}. The initialization of the former
2808 is needed if the called procedures access the command line
2809 (and for backtracing); the latter sets some flags based on the
2810 standard chosen or to enable backtracing. In typical programs,
2811 it is not necessary to call any initialization function.
2813 If your @code{PROGRAM} is compiled with GNU Fortran, you shall
2814 not call any of the following functions. The libgfortran
2815 initialization functions are shown in C syntax but using C
2816 bindings they are also accessible from Fortran.
2819 @node _gfortran_set_args
2820 @subsection @code{_gfortran_set_args} --- Save command-line arguments
2821 @fnindex _gfortran_set_args
2822 @cindex libgfortran initialization, set_args
2825 @item @emph{Description}:
2826 @code{_gfortran_set_args} saves the command-line arguments; this
2827 initialization is required if any of the command-line intrinsics
2828 is called. Additionally, it shall be called if backtracing is
2829 enabled (see @code{_gfortran_set_options}).
2831 @item @emph{Syntax}:
2832 @code{void _gfortran_set_args (int argc, char *argv[])}
2834 @item @emph{Arguments}:
2835 @multitable @columnfractions .15 .70
2836 @item @var{argc} @tab number of command line argument strings
2837 @item @var{argv} @tab the command-line argument strings; argv[0]
2838 is the pathname of the executable itself.
2841 @item @emph{Example}:
2843 int main (int argc, char *argv[])
2845 /* Initialize libgfortran. */
2846 _gfortran_set_args (argc, argv);
2853 @node _gfortran_set_options
2854 @subsection @code{_gfortran_set_options} --- Set library option flags
2855 @fnindex _gfortran_set_options
2856 @cindex libgfortran initialization, set_options
2859 @item @emph{Description}:
2860 @code{_gfortran_set_options} sets several flags related to the Fortran
2861 standard to be used, whether backtracing should be enabled
2862 and whether range checks should be performed. The syntax allows for
2863 upward compatibility since the number of passed flags is specified; for
2864 non-passed flags, the default value is used. See also
2865 @pxref{Code Gen Options}. Please note that not all flags are actually
2868 @item @emph{Syntax}:
2869 @code{void _gfortran_set_options (int num, int options[])}
2871 @item @emph{Arguments}:
2872 @multitable @columnfractions .15 .70
2873 @item @var{num} @tab number of options passed
2874 @item @var{argv} @tab The list of flag values
2877 @item @emph{option flag list}:
2878 @multitable @columnfractions .15 .70
2879 @item @var{option}[0] @tab Allowed standard; can give run-time errors
2880 if e.g. an input-output edit descriptor is invalid in a given standard.
2881 Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1),
2882 @code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4), @code{GFC_STD_F95}
2883 (8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU} (32),
2884 @code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128),
2885 @code{GFC_STD_F2008_OBS} (256) and GFC_STD_F2008_TS (512). Default:
2886 @code{GFC_STD_F95_OBS | GFC_STD_F95_DEL | GFC_STD_F95 | GFC_STD_F2003
2887 | GFC_STD_F2008 | GFC_STD_F2008_TS | GFC_STD_F2008_OBS | GFC_STD_F77
2888 | GFC_STD_GNU | GFC_STD_LEGACY}.
2889 @item @var{option}[1] @tab Standard-warning flag; prints a warning to
2890 standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}.
2891 @item @var{option}[2] @tab If non zero, enable pedantic checking.
2893 @item @var{option}[3] @tab Unused.
2894 @item @var{option}[4] @tab If non zero, enable backtracing on run-time
2895 errors. Default: off. (Default in the compiler: on.)
2896 Note: Installs a signal handler and requires command-line
2897 initialization using @code{_gfortran_set_args}.
2898 @item @var{option}[5] @tab If non zero, supports signed zeros.
2900 @item @var{option}[6] @tab Enables run-time checking. Possible values
2901 are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2),
2902 GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (16), GFC_RTCHECK_POINTER (32).
2904 @item @var{option}[7] @tab Unused.
2905 @item @var{option}[8] @tab Show a warning when invoking @code{STOP} and
2906 @code{ERROR STOP} if a floating-point exception occurred. Possible values
2907 are (bitwise or-ed) @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
2908 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
2909 @code{GFC_FPE_UNDERFLOW} (16), @code{GFC_FPE_INEXACT} (32). Default: None (0).
2910 (Default in the compiler: @code{GFC_FPE_INVALID | GFC_FPE_DENORMAL |
2911 GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW}.)
2914 @item @emph{Example}:
2916 /* Use gfortran 4.9 default options. */
2917 static int options[] = @{68, 511, 0, 0, 1, 1, 0, 0, 31@};
2918 _gfortran_set_options (9, &options);
2923 @node _gfortran_set_convert
2924 @subsection @code{_gfortran_set_convert} --- Set endian conversion
2925 @fnindex _gfortran_set_convert
2926 @cindex libgfortran initialization, set_convert
2929 @item @emph{Description}:
2930 @code{_gfortran_set_convert} set the representation of data for
2933 @item @emph{Syntax}:
2934 @code{void _gfortran_set_convert (int conv)}
2936 @item @emph{Arguments}:
2937 @multitable @columnfractions .15 .70
2938 @item @var{conv} @tab Endian conversion, possible values:
2939 GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1),
2940 GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3).
2943 @item @emph{Example}:
2945 int main (int argc, char *argv[])
2947 /* Initialize libgfortran. */
2948 _gfortran_set_args (argc, argv);
2949 _gfortran_set_convert (1);
2956 @node _gfortran_set_record_marker
2957 @subsection @code{_gfortran_set_record_marker} --- Set length of record markers
2958 @fnindex _gfortran_set_record_marker
2959 @cindex libgfortran initialization, set_record_marker
2962 @item @emph{Description}:
2963 @code{_gfortran_set_record_marker} sets the length of record markers
2964 for unformatted files.
2966 @item @emph{Syntax}:
2967 @code{void _gfortran_set_record_marker (int val)}
2969 @item @emph{Arguments}:
2970 @multitable @columnfractions .15 .70
2971 @item @var{val} @tab Length of the record marker; valid values
2972 are 4 and 8. Default is 4.
2975 @item @emph{Example}:
2977 int main (int argc, char *argv[])
2979 /* Initialize libgfortran. */
2980 _gfortran_set_args (argc, argv);
2981 _gfortran_set_record_marker (8);
2988 @node _gfortran_set_fpe
2989 @subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps
2990 @fnindex _gfortran_set_fpe
2991 @cindex libgfortran initialization, set_fpe
2994 @item @emph{Description}:
2995 @code{_gfortran_set_fpe} enables floating point exception traps for
2996 the specified exceptions. On most systems, this will result in a
2997 SIGFPE signal being sent and the program being aborted.
2999 @item @emph{Syntax}:
3000 @code{void _gfortran_set_fpe (int val)}
3002 @item @emph{Arguments}:
3003 @multitable @columnfractions .15 .70
3004 @item @var{option}[0] @tab IEEE exceptions. Possible values are
3005 (bitwise or-ed) zero (0, default) no trapping,
3006 @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2),
3007 @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8),
3008 @code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32).
3011 @item @emph{Example}:
3013 int main (int argc, char *argv[])
3015 /* Initialize libgfortran. */
3016 _gfortran_set_args (argc, argv);
3017 /* FPE for invalid operations such as SQRT(-1.0). */
3018 _gfortran_set_fpe (1);
3025 @node _gfortran_set_max_subrecord_length
3026 @subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length
3027 @fnindex _gfortran_set_max_subrecord_length
3028 @cindex libgfortran initialization, set_max_subrecord_length
3031 @item @emph{Description}:
3032 @code{_gfortran_set_max_subrecord_length} set the maximum length
3033 for a subrecord. This option only makes sense for testing and
3034 debugging of unformatted I/O.
3036 @item @emph{Syntax}:
3037 @code{void _gfortran_set_max_subrecord_length (int val)}
3039 @item @emph{Arguments}:
3040 @multitable @columnfractions .15 .70
3041 @item @var{val} @tab the maximum length for a subrecord;
3042 the maximum permitted value is 2147483639, which is also
3046 @item @emph{Example}:
3048 int main (int argc, char *argv[])
3050 /* Initialize libgfortran. */
3051 _gfortran_set_args (argc, argv);
3052 _gfortran_set_max_subrecord_length (8);
3059 @node Naming and argument-passing conventions
3060 @section Naming and argument-passing conventions
3062 This section gives an overview about the naming convention of procedures
3063 and global variables and about the argument passing conventions used by
3064 GNU Fortran. If a C binding has been specified, the naming convention
3065 and some of the argument-passing conventions change. If possible,
3066 mixed-language and mixed-compiler projects should use the better defined
3067 C binding for interoperability. See @pxref{Interoperability with C}.
3070 * Naming conventions::
3071 * Argument passing conventions::
3075 @node Naming conventions
3076 @subsection Naming conventions
3078 According the Fortran standard, valid Fortran names consist of a letter
3079 between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0},
3080 @code{1} to @code{9} and underscores (@code{_}) with the restriction
3081 that names may only start with a letter. As vendor extension, the
3082 dollar sign (@code{$}) is additionally permitted with the option
3083 @option{-fdollar-ok}, but not as first character and only if the
3084 target system supports it.
3086 By default, the procedure name is the lower-cased Fortran name with an
3087 appended underscore (@code{_}); using @option{-fno-underscoring} no
3088 underscore is appended while @code{-fsecond-underscore} appends two
3089 underscores. Depending on the target system and the calling convention,
3090 the procedure might be additionally dressed; for instance, on 32bit
3091 Windows with @code{stdcall}, an at-sign @code{@@} followed by an integer
3092 number is appended. For the changing the calling convention, see
3093 @pxref{GNU Fortran Compiler Directives}.
3095 For common blocks, the same convention is used, i.e. by default an
3096 underscore is appended to the lower-cased Fortran name. Blank commons
3097 have the name @code{__BLNK__}.
3099 For procedures and variables declared in the specification space of a
3100 module, the name is formed by @code{__}, followed by the lower-cased
3101 module name, @code{_MOD_}, and the lower-cased Fortran name. Note that
3102 no underscore is appended.
3105 @node Argument passing conventions
3106 @subsection Argument passing conventions
3108 Subroutines do not return a value (matching C99's @code{void}) while
3109 functions either return a value as specified in the platform ABI or
3110 the result variable is passed as hidden argument to the function and
3111 no result is returned. A hidden result variable is used when the
3112 result variable is an array or of type @code{CHARACTER}.
3114 Arguments are passed according to the platform ABI. In particular,
3115 complex arguments might not be compatible to a struct with two real
3116 components for the real and imaginary part. The argument passing
3117 matches the one of C99's @code{_Complex}. Functions with scalar
3118 complex result variables return their value and do not use a
3119 by-reference argument. Note that with the @option{-ff2c} option,
3120 the argument passing is modified and no longer completely matches
3121 the platform ABI. Some other Fortran compilers use @code{f2c}
3122 semantic by default; this might cause problems with
3125 GNU Fortran passes most arguments by reference, i.e. by passing a
3126 pointer to the data. Note that the compiler might use a temporary
3127 variable into which the actual argument has been copied, if required
3128 semantically (copy-in/copy-out).
3130 For arguments with @code{ALLOCATABLE} and @code{POINTER}
3131 attribute (including procedure pointers), a pointer to the pointer
3132 is passed such that the pointer address can be modified in the
3135 For dummy arguments with the @code{VALUE} attribute: Scalar arguments
3136 of the type @code{INTEGER}, @code{LOGICAL}, @code{REAL} and
3137 @code{COMPLEX} are passed by value according to the platform ABI.
3138 (As vendor extension and not recommended, using @code{%VAL()} in the
3139 call to a procedure has the same effect.) For @code{TYPE(C_PTR)} and
3140 procedure pointers, the pointer itself is passed such that it can be
3141 modified without affecting the caller.
3142 @c FIXME: Document how VALUE is handled for CHARACTER, TYPE,
3143 @c CLASS and arrays, i.e. whether the copy-in is done in the caller
3144 @c or in the callee.
3146 For Boolean (@code{LOGICAL}) arguments, please note that GCC expects
3147 only the integer value 0 and 1. If a GNU Fortran @code{LOGICAL}
3148 variable contains another integer value, the result is undefined.
3149 As some other Fortran compilers use @math{-1} for @code{.TRUE.},
3150 extra care has to be taken -- such as passing the value as
3151 @code{INTEGER}. (The same value restriction also applies to other
3152 front ends of GCC, e.g. to GCC's C99 compiler for @code{_Bool}
3153 or GCC's Ada compiler for @code{Boolean}.)
3155 For arguments of @code{CHARACTER} type, the character length is passed
3156 as hidden argument. For deferred-length strings, the value is passed
3157 by reference, otherwise by value. The character length has the type
3158 @code{INTEGER(kind=4)}. Note with C binding, @code{CHARACTER(len=1)}
3159 result variables are returned according to the platform ABI and no
3160 hidden length argument is used for dummy arguments; with @code{VALUE},
3161 those variables are passed by value.
3163 For @code{OPTIONAL} dummy arguments, an absent argument is denoted
3164 by a NULL pointer, except for scalar dummy arguments of type
3165 @code{INTEGER}, @code{LOGICAL}, @code{REAL} and @code{COMPLEX}
3166 which have the @code{VALUE} attribute. For those, a hidden Boolean
3167 argument (@code{logical(kind=C_bool),value}) is used to indicate
3168 whether the argument is present.
3170 Arguments which are assumed-shape, assumed-rank or deferred-rank
3171 arrays or, with @option{-fcoarray=lib}, allocatable scalar coarrays use
3172 an array descriptor. All other arrays pass the address of the
3173 first element of the array. With @option{-fcoarray=lib}, the token
3174 and the offset belonging to nonallocatable coarrays dummy arguments
3175 are passed as hidden argument along the character length hidden
3176 arguments. The token is an oparque pointer identifying the coarray
3177 and the offset is a passed-by-value integer of kind @code{C_PTRDIFF_T},
3178 denoting the byte offset between the base address of the coarray and
3179 the passed scalar or first element of the passed array.
3181 The arguments are passed in the following order
3183 @item Result variable, when the function result is passed by reference
3184 @item Character length of the function result, if it is a of type
3185 @code{CHARACTER} and no C binding is used
3186 @item The arguments in the order in which they appear in the Fortran
3188 @item The the present status for optional arguments with value attribute,
3189 which are internally passed by value
3190 @item The character length and/or coarray token and offset for the first
3191 argument which is a @code{CHARACTER} or a nonallocatable coarray dummy
3192 argument, followed by the hidden arguments of the next dummy argument
3197 @c ---------------------------------------------------------------------
3198 @c Coarray Programming
3199 @c ---------------------------------------------------------------------
3201 @node Coarray Programming
3202 @chapter Coarray Programming
3206 * Type and enum ABI Documentation::
3207 * Function ABI Documentation::
3211 @node Type and enum ABI Documentation
3212 @section Type and enum ABI Documentation
3220 @subsection @code{caf_token_t}
3222 Typedef of type @code{void *} on the compiler side. Can be any data
3223 type on the library side.
3225 @node caf_register_t
3226 @subsection @code{caf_register_t}
3228 Indicates which kind of coarray variable should be registered.
3231 typedef enum caf_register_t {
3232 CAF_REGTYPE_COARRAY_STATIC,
3233 CAF_REGTYPE_COARRAY_ALLOC,
3234 CAF_REGTYPE_LOCK_STATIC,
3235 CAF_REGTYPE_LOCK_ALLOC,
3236 CAF_REGTYPE_CRITICAL
3242 @node Function ABI Documentation
3243 @section Function ABI Documentation
3246 * _gfortran_caf_init:: Initialiation function
3247 * _gfortran_caf_finish:: Finalization function
3248 * _gfortran_caf_this_image:: Querying the image number
3249 * _gfortran_caf_num_images:: Querying the maximal number of images
3250 * _gfortran_caf_register:: Registering coarrays
3251 * _gfortran_caf_deregister:: Deregistering coarrays
3252 * _gfortran_caf_send:: Sending data from a local image to a remote image
3253 * _gfortran_caf_get:: Getting data from a remote image
3254 * _gfortran_caf_sendget:: Sending data between remote images
3255 * _gfortran_caf_lock:: Locking a lock variable
3256 * _gfortran_caf_unlock:: Unlocking a lock variable
3257 * _gfortran_caf_co_broadcast:: Sending data to all images
3258 * _gfortran_caf_co_max:: Collective maximum reduction
3259 * _gfortran_caf_co_min:: Collective minimum reduction
3260 * _gfortran_caf_co_sum:: Collective summing reduction
3261 * _gfortran_caf_co_reduce:: Generic collective reduction
3265 @node _gfortran_caf_init
3266 @subsection @code{_gfortran_caf_init} --- Initialiation function
3267 @cindex Coarray, _gfortran_caf_init
3270 @item @emph{Description}:
3271 This function is called at startup of the program before the Fortran main
3272 program, if the latter has been compiled with @option{-fcoarray=lib}.
3273 It takes as arguments the command-line arguments of the program. It is
3274 permitted to pass to @code{NULL} pointers as argument; if non-@code{NULL},
3275 the library is permitted to modify the arguments.
3277 @item @emph{Syntax}:
3278 @code{void _gfortran_caf_init (int *argc, char ***argv)}
3280 @item @emph{Arguments}:
3281 @multitable @columnfractions .15 .70
3282 @item @var{argc} @tab intent(inout) An integer pointer with the number of
3283 arguments passed to the program or @code{NULL}.
3284 @item @var{argv} @tab intent(inout) A pointer to an array of strings with the
3285 command-line arguments or @code{NULL}.
3289 The function is modelled after the initialization function of the Message
3290 Passing Interface (MPI) specification. Due to the way coarray registration
3291 works, it might not be the first call to the libaray. If the main program is
3292 not written in Fortran and only a library uses coarrays, it can happen that
3293 this function is never called. Therefore, it is recommended that the library
3294 does not rely on the passed arguments and whether the call has been done.
3298 @node _gfortran_caf_finish
3299 @subsection @code{_gfortran_caf_finish} --- Finalization function
3300 @cindex Coarray, _gfortran_caf_finish
3303 @item @emph{Description}:
3304 This function is called at the end of the Fortran main program, if it has
3305 been compiled with the @option{-fcoarray=lib} option.
3307 @item @emph{Syntax}:
3308 @code{void _gfortran_caf_finish (void)}
3311 For non-Fortran programs, it is recommended to call the function at the end
3312 of the main program. To ensure that the shutdown is also performed for
3313 programs where this function is not explicitly invoked, for instance
3314 non-Fortran programs or calls to the system's exit() function, the library
3315 can use a destructor function. Note that programs can also be terminated
3316 using the STOP and ERROR STOP statements; those use different library calls.
3320 @node _gfortran_caf_this_image
3321 @subsection @code{_gfortran_caf_this_image} --- Querying the image number
3322 @cindex Coarray, _gfortran_caf_this_image
3325 @item @emph{Description}:
3326 This function returns the current image number, which is a positive number.
3328 @item @emph{Syntax}:
3329 @code{int _gfortran_caf_this_image (int distance)}
3331 @item @emph{Arguments}:
3332 @multitable @columnfractions .15 .70
3333 @item @var{distance} @tab As specified for the @code{this_image} intrinsic
3334 in TS18508. Shall be a nonnegative number.
3338 If the Fortran intrinsic @code{this_image} is invoked without an argument, which
3339 is the only permitted form in Fortran 2008, GCC passes @code{0} as
3344 @node _gfortran_caf_num_images
3345 @subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images
3346 @cindex Coarray, _gfortran_caf_num_images
3349 @item @emph{Description}:
3350 This function returns the number of images in the current team, if
3351 @var{distance} is 0 or the number of images in the parent team at the specified
3352 distance. If failed is -1, the function returns the number of all images at
3353 the specified distance; if it is 0, the function returns the number of
3354 nonfailed images, and if it is 1, it returns the number of failed images.
3356 @item @emph{Syntax}:
3357 @code{int _gfortran_caf_num_images(int distance, int failed)}
3359 @item @emph{Arguments}:
3360 @multitable @columnfractions .15 .70
3361 @item @var{distance} @tab the distance from this image to the ancestor.
3363 @item @var{failed} @tab shall be -1, 0, or 1
3367 This function follows TS18508. If the num_image intrinsic has no arguments,
3368 the the compiler passes @code{distance=0} and @code{failed=-1} to the function.
3372 @node _gfortran_caf_register
3373 @subsection @code{_gfortran_caf_register} --- Registering coarrays
3374 @cindex Coarray, _gfortran_caf_deregister
3377 @item @emph{Description}:
3378 Allocates memory for a coarray and creates a token to identify the coarray. The
3379 function is called for both coarrays with @code{SAVE} attribute and using an
3380 explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a
3381 @code{NULL} pointer, the function shall abort with printing an error message
3382 and starting the error termination. If no error occurs and @var{STAT} is
3383 present, it shall be set to zero. Otherwise, it shall be set to a positive
3384 value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing
3385 the failure. The function shall return a pointer to the requested memory
3386 for the local image as a call to @code{malloc} would do.
3388 For @code{CAF_REGTYPE_COARRAY_STATIC} and @code{CAF_REGTYPE_COARRAY_ALLOC},
3389 the passed size is the byte size requested. For @code{CAF_REGTYPE_LOCK_STATIC},
3390 @code{CAF_REGTYPE_LOCK_ALLOC} and @code{CAF_REGTYPE_CRITICAL} it is the array
3391 size or one for a scalar.
3394 @item @emph{Syntax}:
3395 @code{void *caf_register (size_t size, caf_register_t type, caf_token_t *token,
3396 int *stat, char *errmsg, int errmsg_len)}
3398 @item @emph{Arguments}:
3399 @multitable @columnfractions .15 .70
3400 @item @var{size} @tab For normal coarrays, the byte size of the coarray to be
3401 allocated; for lock types, the number of elements.
3402 @item @var{type} @tab one of the caf_register_t types.
3403 @item @var{token} @tab intent(out) An opaque pointer identifying the coarray.
3404 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
3406 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3407 an error message; may be NULL
3408 @item @var{errmsg_len} @tab the buffer size of errmsg.
3412 Nonalloatable coarrays have to be registered prior use from remote images.
3413 In order to guarantee this, they have to be registered before the main
3414 program. This can be achieved by creating constructor functions. That is what
3415 GCC does such that also nonallocatable coarrays the memory is allocated and no
3416 static memory is used. The token permits to identify the coarray; to the
3417 processor, the token is a nonaliasing pointer. The library can, for instance,
3418 store the base address of the coarray in the token, some handle or a more
3421 For normal coarrays, the returned pointer is used for accesses on the local
3422 image. For lock types, the value shall only used for checking the allocation
3423 status. Note that for critical blocks, the locking is only required on one
3424 image; in the locking statement, the processor shall always pass always an
3425 image index of one for critical-block lock variables
3426 (@code{CAF_REGTYPE_CRITICAL}).
3430 @node _gfortran_caf_deregister
3431 @subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays
3432 @cindex Coarray, _gfortran_caf_deregister
3435 @item @emph{Description}:
3436 Called to free the memory of a coarray; the processor calls this function for
3437 automatic and explicit deallocation. In case of an error, this function shall
3438 fail with an error message, unless the @var{STAT} variable is not null.
3440 @item @emph{Syntax}:
3441 @code{void caf_deregister (const caf_token_t *token, int *stat, char *errmsg,
3444 @item @emph{Arguments}:
3445 @multitable @columnfractions .15 .70
3446 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
3448 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set
3449 to an error message; may be NULL
3450 @item @var{errmsg_len} @tab the buffer size of errmsg.
3454 For nonalloatable coarrays this function is never called. If a cleanup is
3455 required, it has to be handled via the finish, stop and error stop functions,
3456 and via destructors.
3460 @node _gfortran_caf_send
3461 @subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image
3462 @cindex Coarray, _gfortran_caf_send
3465 @item @emph{Description}:
3466 Called to send a scalar, an array section or whole array from a local
3467 to a remote image identified by the image_index.
3469 @item @emph{Syntax}:
3470 @code{void _gfortran_caf_send (caf_token_t token, size_t offset,
3471 int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
3472 gfc_descriptor_t *src, int dst_kind, int src_kind, bool may_require_tmp)}
3474 @item @emph{Arguments}:
3475 @multitable @columnfractions .15 .70
3476 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3477 @item @var{offset} @tab By which amount of bytes the actual data is shifted
3478 compared to the base address of the coarray.
3479 @item @var{image_index} @tab The ID of the remote image; must be a positive
3481 @item @var{dest} @tab intent(in) Array descriptor for the remote image for the
3482 bounds and the size. The base_addr shall not be accessed.
3483 @item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
3484 subscript of the destination array; the values are relative to the dimension
3485 triplet of the dest argument.
3486 @item @var{src} @tab intent(in) Array descriptor of the local array to be
3487 transferred to the remote image
3488 @item @var{dst_kind} @tab Kind of the destination argument
3489 @item @var{src_kind} @tab Kind of the source argument
3490 @item @var{may_require_tmp} @tab The variable is false it is known at compile
3491 time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
3492 or partially) such that walking @var{src} and @var{dest} in element wise
3493 element order (honoring the stride value) will not lead to wrong results.
3494 Otherwise, the value is true.
3498 It is permitted to have image_id equal the current image; the memory of the
3499 send-to and the send-from might (partially) overlap in that case. The
3500 implementation has to take care that it handles this case, e.g. using
3501 @code{memmove} which handles (partially) overlapping memory. If
3502 @var{may_require_tmp} is true, the library might additionally create a
3503 temporary variable, unless additional checks show that this is not required
3504 (e.g. because walking backward is possible or because both arrays are
3505 contiguous and @code{memmove} takes care of overlap issues).
3507 Note that the assignment of a scalar to an array is permitted. In addition,
3508 the library has to handle numeric-type conversion and for strings, padding
3509 and different character kinds.
3513 @node _gfortran_caf_get
3514 @subsection @code{_gfortran_caf_get} --- Getting data from a remote image
3515 @cindex Coarray, _gfortran_caf_get
3518 @item @emph{Description}:
3519 Called to get an array section or whole array from a a remote,
3520 image identified by the image_index.
3522 @item @emph{Syntax}:
3523 @code{void _gfortran_caf_get_desc (caf_token_t token, size_t offset,
3524 int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector,
3525 gfc_descriptor_t *dest, int src_kind, int dst_kind, bool may_require_tmp)}
3527 @item @emph{Arguments}:
3528 @multitable @columnfractions .15 .70
3529 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3530 @item @var{offset} @tab By which amount of bytes the actual data is shifted
3531 compared to the base address of the coarray.
3532 @item @var{image_index} @tab The ID of the remote image; must be a positive
3534 @item @var{dest} @tab intent(in) Array descriptor of the local array to be
3535 transferred to the remote image
3536 @item @var{src} @tab intent(in) Array descriptor for the remote image for the
3537 bounds and the size. The base_addr shall not be accessed.
3538 @item @var{src_vector} @tab intent(int) If not NULL, it contains the vector
3539 subscript of the destination array; the values are relative to the dimension
3540 triplet of the dest argument.
3541 @item @var{dst_kind} @tab Kind of the destination argument
3542 @item @var{src_kind} @tab Kind of the source argument
3543 @item @var{may_require_tmp} @tab The variable is false it is known at compile
3544 time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
3545 or partially) such that walking @var{src} and @var{dest} in element wise
3546 element order (honoring the stride value) will not lead to wrong results.
3547 Otherwise, the value is true.
3551 It is permitted to have image_id equal the current image; the memory of the
3552 send-to and the send-from might (partially) overlap in that case. The
3553 implementation has to take care that it handles this case, e.g. using
3554 @code{memmove} which handles (partially) overlapping memory. If
3555 @var{may_require_tmp} is true, the library might additionally create a
3556 temporary variable, unless additional checks show that this is not required
3557 (e.g. because walking backward is possible or because both arrays are
3558 contiguous and @code{memmove} takes care of overlap issues).
3560 Note that the library has to handle numeric-type conversion and for strings,
3561 padding and different character kinds.
3565 @node _gfortran_caf_sendget
3566 @subsection @code{_gfortran_caf_sendget} --- Sending data between remote images
3567 @cindex Coarray, _gfortran_caf_sendget
3570 @item @emph{Description}:
3571 Called to send a scalar, an array section or whole array from a remote image
3572 identified by the src_image_index to a remote image identified by the
3575 @item @emph{Syntax}:
3576 @code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset,
3577 int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector,
3578 caf_token_t src_token, size_t src_offset, int src_image_index,
3579 gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind,
3580 bool may_require_tmp)}
3582 @item @emph{Arguments}:
3583 @multitable @columnfractions .15 .70
3584 @item @var{dst_token} @tab intent(in) An opaque pointer identifying the
3585 destination coarray.
3586 @item @var{dst_offset} @tab By which amount of bytes the actual data is
3587 shifted compared to the base address of the destination coarray.
3588 @item @var{dst_image_index} @tab The ID of the destination remote image; must
3589 be a positive number.
3590 @item @var{dest} @tab intent(in) Array descriptor for the destination
3591 remote image for the bounds and the size. The base_addr shall not be accessed.
3592 @item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector
3593 subscript of the destination array; the values are relative to the dimension
3594 triplet of the dest argument.
3595 @item @var{src_token} @tab An opaque pointer identifying the source coarray.
3596 @item @var{src_offset} @tab By which amount of bytes the actual data is shifted
3597 compared to the base address of the source coarray.
3598 @item @var{src_image_index} @tab The ID of the source remote image; must be a
3600 @item @var{src} @tab intent(in) Array descriptor of the local array to be
3601 transferred to the remote image.
3602 @item @var{src_vector} @tab intent(in) Array descriptor of the local array to
3603 be transferred to the remote image
3604 @item @var{dst_kind} @tab Kind of the destination argument
3605 @item @var{src_kind} @tab Kind of the source argument
3606 @item @var{may_require_tmp} @tab The variable is false it is known at compile
3607 time that the @var{dest} and @var{src} either cannot overlap or overlap (fully
3608 or partially) such that walking @var{src} and @var{dest} in element wise
3609 element order (honoring the stride value) will not lead to wrong results.
3610 Otherwise, the value is true.
3614 It is permitted to have image_ids equal; the memory of the send-to and the
3615 send-from might (partially) overlap in that case. The implementation has to
3616 take care that it handles this case, e.g. using @code{memmove} which handles
3617 (partially) overlapping memory. If @var{may_require_tmp} is true, the library
3618 might additionally create a temporary variable, unless additional checks show
3619 that this is not required (e.g. because walking backward is possible or because
3620 both arrays are contiguous and @code{memmove} takes care of overlap issues).
3622 Note that the assignment of a scalar to an array is permitted. In addition,
3623 the library has to handle numeric-type conversion and for strings, padding and
3624 different character kinds.
3628 @node _gfortran_caf_lock
3629 @subsection @code{_gfortran_caf_lock} --- Locking a lock variable
3630 @cindex Coarray, _gfortran_caf_lock
3633 @item @emph{Description}:
3634 Acquire a lock on the given image on a scalar locking variable or for the
3635 given array element for an array-valued variable. If the @var{aquired_lock}
3636 is @code{NULL}, the function return after having obtained the lock. If it is
3637 nonnull, the result is is assigned the value true (one) when the lock could be
3638 obtained and false (zero) otherwise. Locking a lock variable which has already
3639 been locked by the same image is an error.
3641 @item @emph{Syntax}:
3642 @code{void _gfortran_caf_lock (caf_token_t token, size_t index, int image_index,
3643 int *aquired_lock, int *stat, char *errmsg, int errmsg_len)}
3645 @item @emph{Arguments}:
3646 @multitable @columnfractions .15 .70
3647 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3648 @item @var{index} @tab Array index; first array index is 0. For scalars, it is
3650 @item @var{image_index} @tab The ID of the remote image; must be a positive
3652 @item @var{aquired_lock} @tab intent(out) If not NULL, it returns whether lock
3654 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
3656 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3657 an error message; may be NULL
3658 @item @var{errmsg_len} @tab the buffer size of errmsg.
3662 This function is also called for critical blocks; for those, the array index
3663 is always zero and the image index is one. Libraries are permitted to use other
3664 images for critical-block locking variables.
3668 @node _gfortran_caf_unlock
3669 @subsection @code{_gfortran_caf_lock} --- Unlocking a lock variable
3670 @cindex Coarray, _gfortran_caf_unlock
3673 @item @emph{Description}:
3674 Release a lock on the given image on a scalar locking variable or for the
3675 given array element for an array-valued variable. Unlocking a lock variable
3676 which is unlocked or has been locked by a different image is an error.
3678 @item @emph{Syntax}:
3679 @code{void _gfortran_caf_unlock (caf_token_t token, size_t index, int image_index,
3680 int *stat, char *errmsg, int errmsg_len)}
3682 @item @emph{Arguments}:
3683 @multitable @columnfractions .15 .70
3684 @item @var{token} @tab intent(in) An opaque pointer identifying the coarray.
3685 @item @var{index} @tab Array index; first array index is 0. For scalars, it is
3687 @item @var{image_index} @tab The ID of the remote image; must be a positive
3689 @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=;
3691 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3692 an error message; may be NULL
3693 @item @var{errmsg_len} @tab the buffer size of errmsg.
3697 This function is also called for critical block; for those, the array index
3698 is always zero and the image index is one. Libraries are permitted to use other
3699 images for critical-block locking variables.
3704 @node _gfortran_caf_co_broadcast
3705 @subsection @code{_gfortran_caf_co_broadcast} --- Sending data to all images
3706 @cindex Coarray, _gfortran_caf_co_broadcast
3709 @item @emph{Description}:
3710 Distribute a value from a given image to all other images in the team. Has to
3711 be called collectively.
3713 @item @emph{Syntax}:
3714 @code{void _gfortran_caf_co_broadcast (gfc_descriptor_t *a,
3715 int source_image, int *stat, char *errmsg, int errmsg_len)}
3717 @item @emph{Arguments}:
3718 @multitable @columnfractions .15 .70
3719 @item @var{a} @tab intent(inout) And array descriptor with the data to be
3720 breoadcasted (on @var{source_image}) or to be received (other images).
3721 @item @var{source_image} @tab The ID of the image from which the data should
3723 @item @var{stat} @tab intent(out) Stores the status STAT= and my may be NULL.
3724 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3725 an error message; may be NULL
3726 @item @var{errmsg_len} @tab the buffer size of errmsg.
3732 @node _gfortran_caf_co_max
3733 @subsection @code{_gfortran_caf_co_max} --- Collective maximum reduction
3734 @cindex Coarray, _gfortran_caf_co_max
3737 @item @emph{Description}:
3738 Calculates the for the each array element of the variable @var{a} the maximum
3739 value for that element in the current team; if @var{result_image} has the
3740 value 0, the result shall be stored on all images, otherwise, only on the
3741 specified image. This function operates on numeric values and character
3744 @item @emph{Syntax}:
3745 @code{void _gfortran_caf_co_max (gfc_descriptor_t *a, int result_image,
3746 int *stat, char *errmsg, int a_len, int errmsg_len)}
3748 @item @emph{Arguments}:
3749 @multitable @columnfractions .15 .70
3750 @item @var{a} @tab intent(inout) And array descriptor with the data to be
3751 breoadcasted (on @var{source_image}) or to be received (other images).
3752 @item @var{result_image} @tab The ID of the image to which the reduced
3753 value should be copied to; if zero, it has to be copied to all images.
3754 @item @var{stat} @tab intent(out) Stores the status STAT= and my may be NULL.
3755 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3756 an error message; may be NULL
3757 @item @var{a_len} @tab The string length of argument @var{a}.
3758 @item @var{errmsg_len} @tab the buffer size of errmsg.
3762 If @var{result_image} is nonzero, the value on all images except of the
3763 specified one become undefined; hence, the library may make use of this.
3768 @node _gfortran_caf_co_min
3769 @subsection @code{_gfortran_caf_co_min} --- Collective minimum reduction
3770 @cindex Coarray, _gfortran_caf_co_min
3773 @item @emph{Description}:
3774 Calculates the for the each array element of the variable @var{a} the minimum
3775 value for that element in the current team; if @var{result_image} has the
3776 value 0, the result shall be stored on all images, otherwise, only on the
3777 specified image. This function operates on numeric values and character
3780 @item @emph{Syntax}:
3781 @code{void _gfortran_caf_co_min (gfc_descriptor_t *a, int result_image,
3782 int *stat, char *errmsg, int a_len, int errmsg_len)}
3784 @item @emph{Arguments}:
3785 @multitable @columnfractions .15 .70
3786 @item @var{a} @tab intent(inout) And array descriptor with the data to be
3787 breoadcasted (on @var{source_image}) or to be received (other images).
3788 @item @var{result_image} @tab The ID of the image to which the reduced
3789 value should be copied to; if zero, it has to be copied to all images.
3790 @item @var{stat} @tab intent(out) Stores the status STAT= and my may be NULL.
3791 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3792 an error message; may be NULL
3793 @item @var{a_len} @tab The string length of argument @var{a}.
3794 @item @var{errmsg_len} @tab the buffer size of errmsg.
3798 If @var{result_image} is nonzero, the value on all images except of the
3799 specified one become undefined; hence, the library may make use of this.
3804 @node _gfortran_caf_co_sum
3805 @subsection @code{_gfortran_caf_co_sum} --- Collective summing reduction
3806 @cindex Coarray, _gfortran_caf_co_sum
3809 @item @emph{Description}:
3810 Calculates the for the each array element of the variable @var{a} the sum
3811 value for that element in the current team; if @var{result_image} has the
3812 value 0, the result shall be stored on all images, otherwise, only on the
3813 specified image. This function operates on numeric values.
3815 @item @emph{Syntax}:
3816 @code{void _gfortran_caf_co_sum (gfc_descriptor_t *a, int result_image,
3817 int *stat, char *errmsg, int errmsg_len)}
3819 @item @emph{Arguments}:
3820 @multitable @columnfractions .15 .70
3821 @item @var{a} @tab intent(inout) And array descriptor with the data to be
3822 breoadcasted (on @var{source_image}) or to be received (other images).
3823 @item @var{result_image} @tab The ID of the image to which the reduced
3824 value should be copied to; if zero, it has to be copied to all images.
3825 @item @var{stat} @tab intent(out) Stores the status STAT= and my may be NULL.
3826 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3827 an error message; may be NULL
3828 @item @var{errmsg_len} @tab the buffer size of errmsg.
3832 If @var{result_image} is nonzero, the value on all images except of the
3833 specified one become undefined; hence, the library may make use of this.
3838 @node _gfortran_caf_co_reduce
3839 @subsection @code{_gfortran_caf_co_reduce} --- Generic collective reduction
3840 @cindex Coarray, _gfortran_caf_co_reduce
3843 @item @emph{Description}:
3844 Calculates the for the each array element of the variable @var{a} the reduction
3845 value for that element in the current team; if @var{result_image} has the
3846 value 0, the result shall be stored on all images, otherwise, only on the
3847 specified image. The @var{opr} is a pure function doing a mathematically
3848 commutative and associative operation.
3850 The @var{opr_flags} denote the following; the values are bitwise ored.
3851 @code{GFC_CAF_BYREF} (1) if the result should be returned
3852 by value; @code{GFC_CAF_HIDDENLEN} (2) whether the result and argument
3853 string lengths shall be specified as hidden argument;
3854 @code{GFC_CAF_ARG_VALUE} (4) whether the arguments shall be passed by value,
3855 @code{GFC_CAF_ARG_DESC} (8) whether the arguments shall be passed by descriptor.
3858 @item @emph{Syntax}:
3859 @code{void _gfortran_caf_co_reduce (gfc_descriptor_t *a,
3860 void * (*opr) (void *, void *), int opr_flags, int result_image,
3861 int *stat, char *errmsg, int a_len, int errmsg_len)}
3863 @item @emph{Arguments}:
3864 @multitable @columnfractions .15 .70
3865 @item @var{opr} @tab Function pointer to the reduction function.
3866 @item @var{opr_flags} @tab Flags regarding the reduction function
3867 @item @var{a} @tab intent(inout) And array descriptor with the data to be
3868 breoadcasted (on @var{source_image}) or to be received (other images).
3869 @item @var{result_image} @tab The ID of the image to which the reduced
3870 value should be copied to; if zero, it has to be copied to all images.
3871 @item @var{stat} @tab intent(out) Stores the status STAT= and my may be NULL.
3872 @item @var{errmsg} @tab intent(out) When an error occurs, this will be set to
3873 an error message; may be NULL
3874 @item @var{a_len} @tab The string length of argument @var{a}.
3875 @item @var{errmsg_len} @tab the buffer size of errmsg.
3879 If @var{result_image} is nonzero, the value on all images except of the
3880 specified one become undefined; hence, the library may make use of this.
3881 For character arguments, the result is passed as first argument, followed
3882 by the result string length, next come the two string arguments, followed
3883 by the two hidden arguments. With C binding, there are no hidden arguments
3884 and by-reference passing and either only a single character is passed or
3885 an array descriptor.
3889 @c Intrinsic Procedures
3890 @c ---------------------------------------------------------------------
3892 @include intrinsic.texi
3899 @c ---------------------------------------------------------------------
3901 @c ---------------------------------------------------------------------
3904 @unnumbered Contributing
3905 @cindex Contributing
3907 Free software is only possible if people contribute to efforts
3909 We're always in need of more people helping out with ideas
3910 and comments, writing documentation and contributing code.
3912 If you want to contribute to GNU Fortran,
3913 have a look at the long lists of projects you can take on.
3914 Some of these projects are small,
3915 some of them are large;
3916 some are completely orthogonal to the rest of what is
3917 happening on GNU Fortran,
3918 but others are ``mainstream'' projects in need of enthusiastic hackers.
3919 All of these projects are important!
3920 We will eventually get around to the things here,
3921 but they are also things doable by someone who is willing and able.
3926 * Proposed Extensions::
3931 @section Contributors to GNU Fortran
3932 @cindex Contributors
3936 Most of the parser was hand-crafted by @emph{Andy Vaught}, who is
3937 also the initiator of the whole project. Thanks Andy!
3938 Most of the interface with GCC was written by @emph{Paul Brook}.
3940 The following individuals have contributed code and/or
3941 ideas and significant help to the GNU Fortran project
3942 (in alphabetical order):
3945 @item Janne Blomqvist
3946 @item Steven Bosscher
3949 @item Fran@,{c}ois-Xavier Coudert
3953 @item Bernhard Fischer
3955 @item Richard Guenther
3956 @item Richard Henderson
3957 @item Katherine Holcomb
3959 @item Niels Kristian Bech Jensen
3960 @item Steven Johnson
3961 @item Steven G. Kargl
3969 @item Christopher D. Rickett
3970 @item Richard Sandiford
3971 @item Tobias Schl@"uter
3980 The following people have contributed bug reports,
3981 smaller or larger patches,
3982 and much needed feedback and encouragement for the
3983 GNU Fortran project:
3987 @item Dominique d'Humi@`eres
3989 @item Erik Schnetter
3990 @item Joost VandeVondele
3993 Many other individuals have helped debug,
3994 test and improve the GNU Fortran compiler over the past few years,
3995 and we welcome you to do the same!
3996 If you already have done so,
3997 and you would like to see your name listed in the
3998 list above, please contact us.
4006 @item Help build the test suite
4007 Solicit more code for donation to the test suite: the more extensive the
4008 testsuite, the smaller the risk of breaking things in the future! We can
4009 keep code private on request.
4011 @item Bug hunting/squishing
4012 Find bugs and write more test cases! Test cases are especially very
4013 welcome, because it allows us to concentrate on fixing bugs instead of
4014 isolating them. Going through the bugzilla database at
4015 @url{https://gcc.gnu.org/@/bugzilla/} to reduce testcases posted there and
4016 add more information (for example, for which version does the testcase
4017 work, for which versions does it fail?) is also very helpful.
4022 @node Proposed Extensions
4023 @section Proposed Extensions
4025 Here's a list of proposed extensions for the GNU Fortran compiler, in no particular
4026 order. Most of these are necessary to be fully compatible with
4027 existing Fortran compilers, but they are not part of the official
4028 J3 Fortran 95 standard.
4030 @subsection Compiler extensions:
4033 User-specified alignment rules for structures.
4036 Automatically extend single precision constants to double.
4039 Compile code that conserves memory by dynamically allocating common and
4040 module storage either on stack or heap.
4043 Compile flag to generate code for array conformance checking (suggest -CC).
4046 User control of symbol names (underscores, etc).
4049 Compile setting for maximum size of stack frame size before spilling
4050 parts to static or heap.
4053 Flag to force local variables into static space.
4056 Flag to force local variables onto stack.
4060 @subsection Environment Options
4063 Pluggable library modules for random numbers, linear algebra.
4064 LA should use BLAS calling conventions.
4067 Environment variables controlling actions on arithmetic exceptions like
4068 overflow, underflow, precision loss---Generate NaN, abort, default.
4072 Set precision for fp units that support it (i387).
4075 Variable for setting fp rounding mode.
4078 Variable to fill uninitialized variables with a user-defined bit
4082 Environment variable controlling filename that is opened for that unit
4086 Environment variable to clear/trash memory being freed.
4089 Environment variable to control tracing of allocations and frees.
4092 Environment variable to display allocated memory at normal program end.
4095 Environment variable for filename for * IO-unit.
4098 Environment variable for temporary file directory.
4101 Environment variable forcing standard output to be line buffered (Unix).
4106 @c ---------------------------------------------------------------------
4107 @c GNU General Public License
4108 @c ---------------------------------------------------------------------
4110 @include gpl_v3.texi
4114 @c ---------------------------------------------------------------------
4115 @c GNU Free Documentation License
4116 @c ---------------------------------------------------------------------
4122 @c ---------------------------------------------------------------------
4123 @c Funding Free Software
4124 @c ---------------------------------------------------------------------
4126 @include funding.texi
4128 @c ---------------------------------------------------------------------
4130 @c ---------------------------------------------------------------------
4133 @unnumbered Option Index
4134 @command{gfortran}'s command line options are indexed here without any
4135 initial @samp{-} or @samp{--}. Where an option has both positive and
4136 negative forms (such as -foption and -fno-option), relevant entries in
4137 the manual are indexed under the most appropriate form; it may sometimes
4138 be useful to look up both forms.
4142 @unnumbered Keyword Index