1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename gfortran.info 4@set copyrights-gfortran 1999-2021 5 6@include gcc-common.texi 7 8@settitle The GNU Fortran Compiler 9 10@c Create a separate index for command line options 11@defcodeindex op 12@c Merge the standard indexes into a single one. 13@syncodeindex fn cp 14@syncodeindex vr cp 15@syncodeindex ky cp 16@syncodeindex pg cp 17@syncodeindex tp cp 18 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. 22 23@tex 24\gdef\part#1#2{% 25 \pchapsepmacro 26 \gdef\thischapter{} 27 \begingroup 28 \vglue\titlepagetopglue 29 \titlefonts \rm 30 \leftline{Part #1:@* #2} 31 \vskip4pt \hrule height 4pt width \hsize \vskip4pt 32 \endgroup 33 \writetocentry{part}{#2}{#1} 34} 35\gdef\blankpart{% 36 \writetocentry{blankpart}{}{} 37} 38% Part TOC-entry definition for summary contents. 39\gdef\dosmallpartentry#1#2#3#4{% 40 \vskip .5\baselineskip plus.2\baselineskip 41 \begingroup 42 \let\rm=\bf \rm 43 \tocentry{Part #2: #1}{\doshortpageno\bgroup#4\egroup} 44 \endgroup 45} 46\gdef\dosmallblankpartentry#1#2#3#4{% 47 \vskip .5\baselineskip plus.2\baselineskip 48} 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 51% outline is created. 52\gdef\dopartentry#1#2#3#4{% 53 \unnchapentry{Part #2: #1}{}{#3}{#4} 54} 55\gdef\doblankpartentry#1#2#3#4{} 56@end tex 57 58@c %**end of header 59 60@c Use with @@smallbook. 61 62@c %** start of document 63 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. 68 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 71@c hand margin. 72@c (To provide the reverse effect, set bindingoffset to -0.75in.) 73 74@c @tex 75@c \global\bindingoffset=0.75in 76@c \global\normaloffset =0.75in 77@c @end tex 78 79@copying 80Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation, Inc. 81 82Permission is granted to copy, distribute and/or modify this document 83under the terms of the GNU Free Documentation License, Version 1.3 or 84any later version published by the Free Software Foundation; with the 85Invariant Sections being ``Funding Free Software'', the Front-Cover 86Texts 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''. 89 90(a) The FSF's Front-Cover Text is: 91 92 A GNU Manual 93 94(b) The FSF's Back-Cover Text is: 95 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. 99@end copying 100 101@ifinfo 102@dircategory Software development 103@direntry 104* gfortran: (gfortran). The GNU Fortran Compiler. 105@end direntry 106This file documents the use and the internals of 107the GNU Fortran compiler, (@command{gfortran}). 108 109Published by the Free Software Foundation 11051 Franklin Street, Fifth Floor 111Boston, MA 02110-1301 USA 112 113@insertcopying 114@end ifinfo 115 116 117@setchapternewpage odd 118@titlepage 119@title Using GNU Fortran 120@versionsubtitle 121@author The @t{gfortran} team 122@page 123@vskip 0pt plus 1filll 124Published by the Free Software Foundation@* 12551 Franklin Street, Fifth Floor@* 126Boston, MA 02110-1301, USA@* 127@c Last printed ??ber, 19??.@* 128@c Printed copies are available for $? each.@* 129@c ISBN ??? 130@sp 1 131@insertcopying 132@end titlepage 133 134@c TODO: The following "Part" definitions are included here temporarily 135@c until they are incorporated into the official Texinfo distribution. 136 137@tex 138\global\let\partentry=\dosmallpartentry 139\global\let\blankpartentry=\dosmallblankpartentry 140@end tex 141@summarycontents 142 143@tex 144\global\let\partentry=\dopartentry 145\global\let\blankpartentry=\doblankpartentry 146@end tex 147@contents 148 149@page 150 151@c --------------------------------------------------------------------- 152@c TexInfo table of contents. 153@c --------------------------------------------------------------------- 154 155@ifnottex 156@node Top 157@top Introduction 158@cindex Introduction 159 160This manual documents the use of @command{gfortran}, 161the GNU Fortran compiler. You can find in this manual how to invoke 162@command{gfortran}, as well as its features and incompatibilities. 163 164@ifset DEVELOPMENT 165@emph{Warning:} This document, and the compiler it describes, are still 166under development. While efforts are made to keep it up-to-date, it might 167not accurately reflect the status of the most recent GNU Fortran compiler. 168@end ifset 169 170@comment 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. 174@comment 175@menu 176* Introduction:: 177 178Part I: Invoking GNU Fortran 179* Invoking GNU Fortran:: Command options supported by @command{gfortran}. 180* Runtime:: Influencing runtime behavior with environment variables. 181 182Part II: Language Reference 183* Fortran standards status:: Fortran 2003, 2008 and 2018 features supported by GNU Fortran. 184* Compiler Characteristics:: User-visible implementation details. 185* Extensions:: Language extensions implemented by GNU Fortran. 186* Mixed-Language Programming:: Interoperability with C 187* Coarray Programming:: 188* Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran. 189* Intrinsic Modules:: Intrinsic modules supported by GNU Fortran. 190 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 199@end menu 200@end ifnottex 201 202@c --------------------------------------------------------------------- 203@c Introduction 204@c --------------------------------------------------------------------- 205 206@node Introduction 207@chapter Introduction 208 209@c The following duplicates the text on the TexInfo table of contents. 210@iftex 211This manual documents the use of @command{gfortran}, the GNU Fortran 212compiler. You can find in this manual how to invoke @command{gfortran}, 213as well as its features and incompatibilities. 214 215@ifset DEVELOPMENT 216@emph{Warning:} This document, and the compiler it describes, are still 217under development. While efforts are made to keep it up-to-date, it 218might not accurately reflect the status of the most recent GNU Fortran 219compiler. 220@end ifset 221@end iftex 222 223The GNU Fortran compiler front end was 224designed initially as a free replacement for, 225or alternative to, the Unix @command{f95} command; 226@command{gfortran} is the command you will use to invoke the compiler. 227 228@menu 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. 235@end menu 236 237 238@c --------------------------------------------------------------------- 239@c About GNU Fortran 240@c --------------------------------------------------------------------- 241 242@node About GNU Fortran 243@section About GNU Fortran 244 245The GNU Fortran compiler supports the Fortran 77, 90 and 95 standards 246completely, parts of the Fortran 2003, 2008 and 2018 standards, and 247several vendor extensions. The development goal is to provide the 248following features: 249 250@itemize @bullet 251@item 252Read a user's program, stored in a file and containing instructions 253written in Fortran 77, Fortran 90, Fortran 95, Fortran 2003, Fortran 2542008 or Fortran 2018. This file contains @dfn{source code}. 255 256@item 257Translate the user's program into instructions a computer 258can carry out more quickly than it takes to translate the 259instructions in the first 260place. The result after compilation of a program is 261@dfn{machine code}, 262code designed to be efficiently translated and processed 263by a machine such as your computer. 264Humans usually are not as good writing machine code 265as they are at writing Fortran (or C++, Ada, or Java), 266because it is easy to make tiny mistakes writing machine code. 267 268@item 269Provide the user with information about the reasons why 270the compiler is unable to create a binary from the source code. 271Usually this will be the case if the source code is flawed. 272The Fortran 90 standard requires that the compiler can point out 273mistakes to the user. 274An incorrect usage of the language causes an @dfn{error message}. 275 276The compiler will also attempt to diagnose cases where the 277user's program contains a correct usage of the language, 278but instructs the computer to do something questionable. 279This kind of diagnostics message is called a @dfn{warning message}. 280 281@item 282Provide optional information about the translation passes 283from the source code to machine code. 284This can help a user of the compiler to find the cause of 285certain bugs which may not be obvious in the source code, 286but may be more easily found at a lower level compiler output. 287It also helps developers to find bugs in the compiler itself. 288 289@item 290Provide information in the generated machine code that can 291make it easier to find bugs in the program (using a debugging tool, 292called a @dfn{debugger}, such as the GNU Debugger @command{gdb}). 293 294@item 295Locate and gather machine code already generated to 296perform actions requested by statements in the user's program. 297This machine code is organized into @dfn{modules} and is located 298and @dfn{linked} to the user program. 299@end itemize 300 301The GNU Fortran compiler consists of several components: 302 303@itemize @bullet 304@item 305A version of the @command{gcc} command 306(which also might be installed as the system's @command{cc} command) 307that also understands and accepts Fortran source code. 308The @command{gcc} command is the @dfn{driver} program for 309all the languages in the GNU Compiler Collection (GCC); 310With @command{gcc}, 311you can compile the source code of any language for 312which a front end is available in GCC. 313 314@item 315The @command{gfortran} command itself, 316which also might be installed as the 317system's @command{f95} command. 318@command{gfortran} is just another driver program, 319but specifically for the Fortran compiler only. 320The difference with @command{gcc} is that @command{gfortran} 321will automatically link the correct libraries to your program. 322 323@item 324A collection of run-time libraries. 325These libraries contain the machine code needed to support 326capabilities of the Fortran language that are not directly 327provided by the machine code generated by the 328@command{gfortran} compilation phase, 329such as intrinsic functions and subroutines, 330and routines for interaction with files and the operating system. 331@c and mechanisms to spawn, 332@c unleash and pause threads in parallelized code. 333 334@item 335The Fortran compiler itself, (@command{f951}). 336This is the GNU Fortran parser and code generator, 337linked to and interfaced with the GCC backend library. 338@command{f951} ``translates'' the source code to 339assembler code. You would typically not use this 340program directly; 341instead, the @command{gcc} or @command{gfortran} driver 342programs will call it for you. 343@end itemize 344 345 346@c --------------------------------------------------------------------- 347@c GNU Fortran and GCC 348@c --------------------------------------------------------------------- 349 350@node GNU Fortran and GCC 351@section GNU Fortran and GCC 352@cindex GNU Compiler Collection 353@cindex GCC 354 355GNU Fortran is a part of GCC, the @dfn{GNU Compiler Collection}. GCC 356consists of a collection of front ends for various languages, which 357translate the source code into a language-independent form called 358@dfn{GENERIC}. This is then processed by a common middle end which 359provides optimization, and then passed to one of a collection of back 360ends which generate code for different computer architectures and 361operating systems. 362 363Functionally, this is implemented with a driver program (@command{gcc}) 364which provides the command-line interface for the compiler. It calls 365the relevant compiler front-end program (e.g., @command{f951} for 366Fortran) for each file in the source code, and then calls the assembler 367and linker as appropriate to produce the compiled output. In a copy of 368GCC which has been compiled with Fortran language support enabled, 369@command{gcc} will recognize files with @file{.f}, @file{.for}, @file{.ftn}, 370@file{.f90}, @file{.f95}, @file{.f03} and @file{.f08} extensions as 371Fortran source code, and compile it accordingly. A @command{gfortran} 372driver program is also provided, which is identical to @command{gcc} 373except that it automatically links the Fortran runtime libraries into the 374compiled program. 375 376Source files with @file{.f}, @file{.for}, @file{.fpp}, @file{.ftn}, @file{.F}, 377@file{.FOR}, @file{.FPP}, and @file{.FTN} extensions are treated as fixed form. 378Source files with @file{.f90}, @file{.f95}, @file{.f03}, @file{.f08}, 379@file{.F90}, @file{.F95}, @file{.F03} and @file{.F08} extensions are 380treated as free form. The capitalized versions of either form are run 381through preprocessing. Source files with the lower case @file{.fpp} 382extension are also run through preprocessing. 383 384This manual specifically documents the Fortran front end, which handles 385the programming language's syntax and semantics. The aspects of GCC 386which relate to the optimization passes and the back-end code generation 387are documented in the GCC manual; see 388@ref{Top,,Introduction,gcc,Using the GNU Compiler Collection (GCC)}. 389The two manuals together provide a complete reference for the GNU 390Fortran compiler. 391 392 393@c --------------------------------------------------------------------- 394@c Preprocessing and conditional compilation 395@c --------------------------------------------------------------------- 396 397@node Preprocessing and conditional compilation 398@section Preprocessing and conditional compilation 399@cindex CPP 400@cindex FPP 401@cindex Conditional compilation 402@cindex Preprocessing 403@cindex preprocessor, include file handling 404 405Many Fortran compilers including GNU Fortran allow passing the source code 406through a C preprocessor (CPP; sometimes also called the Fortran preprocessor, 407FPP) to allow for conditional compilation. In the case of GNU Fortran, 408this is the GNU C Preprocessor in the traditional mode. On systems with 409case-preserving file names, the preprocessor is automatically invoked if the 410filename extension is @file{.F}, @file{.FOR}, @file{.FTN}, @file{.fpp}, 411@file{.FPP}, @file{.F90}, @file{.F95}, @file{.F03} or @file{.F08}. To manually 412invoke the preprocessor on any file, use @option{-cpp}, to disable 413preprocessing on files where the preprocessor is run automatically, use 414@option{-nocpp}. 415 416If a preprocessed file includes another file with the Fortran @code{INCLUDE} 417statement, the included file is not preprocessed. To preprocess included 418files, use the equivalent preprocessor statement @code{#include}. 419 420If GNU Fortran invokes the preprocessor, @code{__GFORTRAN__} 421is defined. The macros @code{__GNUC__}, @code{__GNUC_MINOR__} and 422@code{__GNUC_PATCHLEVEL__} can be used to determine the version of the 423compiler. See @ref{Top,,Overview,cpp,The C Preprocessor} for details. 424 425GNU Fortran supports a number of @code{INTEGER} and @code{REAL} kind types 426in additional to the kind types required by the Fortran standard. 427The availability of any given kind type is architecture dependent. The 428following pre-defined preprocessor macros can be used to conditionally 429include code for these additional kind types: @code{__GFC_INT_1__}, 430@code{__GFC_INT_2__}, @code{__GFC_INT_8__}, @code{__GFC_INT_16__}, 431@code{__GFC_REAL_10__}, and @code{__GFC_REAL_16__}. 432 433While CPP is the de-facto standard for preprocessing Fortran code, 434Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines 435Conditional Compilation, which is not widely used and not directly 436supported by the GNU Fortran compiler. You can use the program coco 437to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}). 438 439 440@c --------------------------------------------------------------------- 441@c GNU Fortran and G77 442@c --------------------------------------------------------------------- 443 444@node GNU Fortran and G77 445@section GNU Fortran and G77 446@cindex Fortran 77 447@cindex @command{g77} 448 449The GNU Fortran compiler is the successor to @command{g77}, the Fortran 45077 front end included in GCC prior to version 4. It is an entirely new 451program that has been designed to provide Fortran 95 support and 452extensibility for future Fortran language standards, as well as providing 453backwards compatibility for Fortran 77 and nearly all of the GNU language 454extensions supported by @command{g77}. 455 456 457@c --------------------------------------------------------------------- 458@c Project Status 459@c --------------------------------------------------------------------- 460 461@node Project Status 462@section Project Status 463 464@quotation 465As soon as @command{gfortran} can parse all of the statements correctly, 466it will be in the ``larva'' state. 467When we generate code, the ``puppa'' state. 468When @command{gfortran} is done, 469we'll see if it will be a beautiful butterfly, 470or just a big bug.... 471 472--Andy Vaught, April 2000 473@end quotation 474 475The start of the GNU Fortran 95 project was announced on 476the GCC homepage in March 18, 2000 477(even though Andy had already been working on it for a while, 478of course). 479 480The GNU Fortran compiler is able to compile nearly all 481standard-compliant Fortran 95, Fortran 90, and Fortran 77 programs, 482including a number of standard and non-standard extensions, and can be 483used on real-world programs. In particular, the supported extensions 484include OpenMP, Cray-style pointers, some old vendor extensions, and several 485Fortran 2003 and Fortran 2008 features, including TR 15581. However, it is 486still under development and has a few remaining rough edges. 487There also is initial support for OpenACC. 488 489At present, the GNU Fortran compiler passes the 490@uref{http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html, 491NIST Fortran 77 Test Suite}, and produces acceptable results on the 492@uref{http://www.netlib.org/lapack/faq.html#1.21, LAPACK Test Suite}. 493It also provides respectable performance on 494the @uref{http://www.polyhedron.com/fortran-compiler-comparisons/polyhedron-benchmark-suite, 495Polyhedron Fortran 496compiler benchmarks} and the 497@uref{http://www.netlib.org/benchmark/livermore, 498Livermore Fortran Kernels test}. It has been used to compile a number of 499large real-world programs, including 500@uref{http://hirlam.org/, the HARMONIE and HIRLAM weather forecasting code} and 501@uref{http://physical-chemistry.scb.uwa.edu.au/tonto/wiki/index.php/Main_Page, 502the Tonto quantum chemistry package}; see 503@url{https://gcc.gnu.org/@/wiki/@/GfortranApps} for an extended list. 504 505Among other things, the GNU Fortran compiler is intended as a replacement 506for G77. At this point, nearly all programs that could be compiled with 507G77 can be compiled with GNU Fortran, although there are a few minor known 508regressions. 509 510The primary work remaining to be done on GNU Fortran falls into three 511categories: bug fixing (primarily regarding the treatment of invalid 512code and providing useful error messages), improving the compiler 513optimizations and the performance of compiled code, and extending the 514compiler to support future standards---in particular, Fortran 2003, 515Fortran 2008 and Fortran 2018. 516 517 518@c --------------------------------------------------------------------- 519@c Standards 520@c --------------------------------------------------------------------- 521 522@node Standards 523@section Standards 524@cindex Standards 525 526@menu 527* Varying Length Character Strings:: 528@end menu 529 530The GNU Fortran compiler implements 531ISO/IEC 1539:1997 (Fortran 95). As such, it can also compile essentially all 532standard-compliant Fortran 90 and Fortran 77 programs. It also supports 533the ISO/IEC TR-15581 enhancements to allocatable arrays. 534 535GNU Fortran also have a partial support for ISO/IEC 1539-1:2004 536(Fortran 2003), ISO/IEC 1539-1:2010 (Fortran 2008), the Technical 537Specification @code{Further Interoperability of Fortran with C} 538(ISO/IEC TS 29113:2012). Full support of those standards and future 539Fortran standards is planned. The current status of the support is 540can be found in the @ref{Fortran 2003 status}, @ref{Fortran 2008 541status} and @ref{Fortran 2018 status} sections of the documentation. 542 543Additionally, the GNU Fortran compilers supports the OpenMP specification 544(version 4.5 and partial support of the features of the 5.0 version, 545@url{http://openmp.org/@/openmp-specifications/}). 546There also is support for the OpenACC specification (targeting 547version 2.6, @uref{http://www.openacc.org/}). See 548@uref{https://gcc.gnu.org/wiki/OpenACC} for more information. 549 550@node Varying Length Character Strings 551@subsection Varying Length Character Strings 552@cindex Varying length character strings 553@cindex Varying length strings 554@cindex strings, varying length 555 556The Fortran 95 standard specifies in Part 2 (ISO/IEC 1539-2:2000) 557varying length character strings. While GNU Fortran currently does not 558support such strings directly, there exist two Fortran implementations 559for them, which work with GNU Fortran. They can be found at 560@uref{http://www.fortran.com/@/iso_varying_string.f95} and at 561@uref{ftp://ftp.nag.co.uk/@/sc22wg5/@/ISO_VARYING_STRING/}. 562 563Deferred-length character strings of Fortran 2003 supports part of 564the features of @code{ISO_VARYING_STRING} and should be considered as 565replacement. (Namely, allocatable or pointers of the type 566@code{character(len=:)}.) 567 568 569@c ===================================================================== 570@c PART I: INVOCATION REFERENCE 571@c ===================================================================== 572 573@tex 574\part{I}{Invoking GNU Fortran} 575@end tex 576 577@c --------------------------------------------------------------------- 578@c Compiler Options 579@c --------------------------------------------------------------------- 580 581@include invoke.texi 582 583 584@c --------------------------------------------------------------------- 585@c Runtime 586@c --------------------------------------------------------------------- 587 588@node Runtime 589@chapter Runtime: Influencing runtime behavior with environment variables 590@cindex environment variable 591 592The behavior of the @command{gfortran} can be influenced by 593environment variables. 594 595Malformed environment variables are silently ignored. 596 597@menu 598* TMPDIR:: Directory for scratch files 599* GFORTRAN_STDIN_UNIT:: Unit number for standard input 600* GFORTRAN_STDOUT_UNIT:: Unit number for standard output 601* GFORTRAN_STDERR_UNIT:: Unit number for standard error 602* GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units 603* GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units. 604* GFORTRAN_SHOW_LOCUS:: Show location for runtime errors 605* GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted 606* GFORTRAN_LIST_SEPARATOR:: Separator for list output 607* GFORTRAN_CONVERT_UNIT:: Set endianness for unformatted I/O 608* GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors 609* GFORTRAN_FORMATTED_BUFFER_SIZE:: Buffer size for formatted files 610* GFORTRAN_UNFORMATTED_BUFFER_SIZE:: Buffer size for unformatted files 611@end menu 612 613@node TMPDIR 614@section @env{TMPDIR}---Directory for scratch files 615 616When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to 617create the file in one of the potential directories by testing each 618directory in the order below. 619 620@enumerate 621@item 622The environment variable @env{TMPDIR}, if it exists. 623 624@item 625On the MinGW target, the directory returned by the @code{GetTempPath} 626function. Alternatively, on the Cygwin target, the @env{TMP} and 627@env{TEMP} environment variables, if they exist, in that order. 628 629@item 630The @code{P_tmpdir} macro if it is defined, otherwise the directory 631@file{/tmp}. 632@end enumerate 633 634@node GFORTRAN_STDIN_UNIT 635@section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input 636 637This environment variable can be used to select the unit number 638preconnected to standard input. This must be a positive integer. 639The default value is 5. 640 641@node GFORTRAN_STDOUT_UNIT 642@section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output 643 644This environment variable can be used to select the unit number 645preconnected to standard output. This must be a positive integer. 646The default value is 6. 647 648@node GFORTRAN_STDERR_UNIT 649@section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error 650 651This environment variable can be used to select the unit number 652preconnected to standard error. This must be a positive integer. 653The default value is 0. 654 655@node GFORTRAN_UNBUFFERED_ALL 656@section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units 657 658This environment variable controls whether all I/O is unbuffered. If 659the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is 660unbuffered. This will slow down small sequential reads and writes. If 661the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. 662This is the default. 663 664@node GFORTRAN_UNBUFFERED_PRECONNECTED 665@section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units 666 667The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls 668whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) is unbuffered. If 669the first letter is @samp{y}, @samp{Y} or @samp{1}, I/O is unbuffered. This 670will slow down small sequential reads and writes. If the first letter 671is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. This is the default. 672 673@node GFORTRAN_SHOW_LOCUS 674@section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors 675 676If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and 677line numbers for runtime errors are printed. If the first letter is 678@samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers 679for runtime errors. The default is to print the location. 680 681@node GFORTRAN_OPTIONAL_PLUS 682@section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted 683 684If the first letter is @samp{y}, @samp{Y} or @samp{1}, 685a plus sign is printed 686where permitted by the Fortran standard. If the first letter 687is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed 688in most cases. Default is not to print plus signs. 689 690@node GFORTRAN_LIST_SEPARATOR 691@section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output 692 693This environment variable specifies the separator when writing 694list-directed output. It may contain any number of spaces and 695at most one comma. If you specify this on the command line, 696be sure to quote spaces, as in 697@smallexample 698$ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out 699@end smallexample 700when @command{a.out} is the compiled Fortran program that you want to run. 701Default is a single space. 702 703@node GFORTRAN_CONVERT_UNIT 704@section @env{GFORTRAN_CONVERT_UNIT}---Set endianness for unformatted I/O 705 706By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible 707to change the representation of data for unformatted files. 708The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable is: 709@smallexample 710GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ; 711mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ; 712exception: mode ':' unit_list | unit_list ; 713unit_list: unit_spec | unit_list unit_spec ; 714unit_spec: INTEGER | INTEGER '-' INTEGER ; 715@end smallexample 716The variable consists of an optional default mode, followed by 717a list of optional exceptions, which are separated by semicolons 718from the preceding default and each other. Each exception consists 719of a format and a comma-separated list of units. Valid values for 720the modes are the same as for the @code{CONVERT} specifier: 721 722@itemize @w{} 723@item @code{NATIVE} Use the native format. This is the default. 724@item @code{SWAP} Swap between little- and big-endian. 725@item @code{LITTLE_ENDIAN} Use the little-endian format 726for unformatted files. 727@item @code{BIG_ENDIAN} Use the big-endian format for unformatted files. 728@end itemize 729A missing mode for an exception is taken to mean @code{BIG_ENDIAN}. 730Examples of values for @env{GFORTRAN_CONVERT_UNIT} are: 731@itemize @w{} 732@item @code{'big_endian'} Do all unformatted I/O in big_endian mode. 733@item @code{'little_endian;native:10-20,25'} Do all unformatted I/O 734in little_endian mode, except for units 10 to 20 and 25, which are in 735native format. 736@item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native. 737@end itemize 738 739Setting the environment variables should be done on the command 740line or via the @command{export} 741command for @command{sh}-compatible shells and via @command{setenv} 742for @command{csh}-compatible shells. 743 744Example for @command{sh}: 745@smallexample 746$ gfortran foo.f90 747$ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out 748@end smallexample 749 750Example code for @command{csh}: 751@smallexample 752% gfortran foo.f90 753% setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20' 754% ./a.out 755@end smallexample 756 757Using anything but the native representation for unformatted data 758carries a significant speed overhead. If speed in this area matters 759to you, it is best if you use this only for data that needs to be 760portable. 761 762@xref{CONVERT specifier}, for an alternative way to specify the 763data representation for unformatted files. @xref{Runtime Options}, for 764setting a default data representation for the whole program. The 765@code{CONVERT} specifier overrides the @option{-fconvert} compile options. 766 767@emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT 768environment variable will override the CONVERT specifier in the 769open statement}. This is to give control over data formats to 770users who do not have the source code of their program available. 771 772@node GFORTRAN_ERROR_BACKTRACE 773@section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors 774 775If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to @samp{y}, 776@samp{Y} or @samp{1} (only the first letter is relevant) then a 777backtrace is printed when a serious run-time error occurs. To disable 778the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}. 779Default is to print a backtrace unless the @option{-fno-backtrace} 780compile option was used. 781 782@node GFORTRAN_FORMATTED_BUFFER_SIZE 783@section @env{GFORTRAN_FORMATTED_BUFFER_SIZE}---Set buffer size for formatted I/O 784 785The @env{GFORTRAN_FORMATTED_BUFFER_SIZE} environment variable 786specifies buffer size in bytes to be used for formatted output. 787The default value is 8192. 788 789@node GFORTRAN_UNFORMATTED_BUFFER_SIZE 790@section @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE}---Set buffer size for unformatted I/O 791 792The @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE} environment variable 793specifies buffer size in bytes to be used for unformatted output. 794The default value is 131072. 795 796@c ===================================================================== 797@c PART II: LANGUAGE REFERENCE 798@c ===================================================================== 799 800@tex 801\part{II}{Language Reference} 802@end tex 803 804@c --------------------------------------------------------------------- 805@c Fortran standards status 806@c --------------------------------------------------------------------- 807 808@node Fortran standards status 809@chapter Fortran standards status 810 811@menu 812* Fortran 2003 status:: 813* Fortran 2008 status:: 814* Fortran 2018 status:: 815@end menu 816 817@node Fortran 2003 status 818@section Fortran 2003 status 819 820GNU Fortran supports several Fortran 2003 features; an incomplete 821list can be found below. See also the 822@uref{https://gcc.gnu.org/wiki/Fortran2003, wiki page} about Fortran 2003. 823 824@itemize 825@item Procedure pointers including procedure-pointer components with 826@code{PASS} attribute. 827 828@item Procedures which are bound to a derived type (type-bound procedures) 829including @code{PASS}, @code{PROCEDURE} and @code{GENERIC}, and 830operators bound to a type. 831 832@item Abstract interfaces and type extension with the possibility to 833override type-bound procedures or to have deferred binding. 834 835@item Polymorphic entities (``@code{CLASS}'') for derived types and unlimited 836polymorphism (``@code{CLASS(*)}'') -- including @code{SAME_TYPE_AS}, 837@code{EXTENDS_TYPE_OF} and @code{SELECT TYPE} for scalars and arrays and 838finalization. 839 840@item Generic interface names, which have the same name as derived types, 841are now supported. This allows one to write constructor functions. Note 842that Fortran does not support static constructor functions. For static 843variables, only default initialization or structure-constructor 844initialization are available. 845 846@item The @code{ASSOCIATE} construct. 847 848@item Interoperability with C including enumerations, 849 850@item In structure constructors the components with default values may be 851omitted. 852 853@item Extensions to the @code{ALLOCATE} statement, allowing for a 854type-specification with type parameter and for allocation and initialization 855from a @code{SOURCE=} expression; @code{ALLOCATE} and @code{DEALLOCATE} 856optionally return an error message string via @code{ERRMSG=}. 857 858@item Reallocation on assignment: If an intrinsic assignment is 859used, an allocatable variable on the left-hand side is automatically allocated 860(if unallocated) or reallocated (if the shape is different). Currently, scalar 861deferred character length left-hand sides are correctly handled but arrays 862are not yet fully implemented. 863 864@item Deferred-length character variables and scalar deferred-length character 865components of derived types are supported. (Note that array-valued components 866are not yet implemented.) 867 868@item Transferring of allocations via @code{MOVE_ALLOC}. 869 870@item The @code{PRIVATE} and @code{PUBLIC} attributes may be given individually 871to derived-type components. 872 873@item In pointer assignments, the lower bound may be specified and 874the remapping of elements is supported. 875 876@item For pointers an @code{INTENT} may be specified which affect the 877association status not the value of the pointer target. 878 879@item Intrinsics @code{command_argument_count}, @code{get_command}, 880@code{get_command_argument}, and @code{get_environment_variable}. 881 882@item Support for Unicode characters (ISO 10646) and UTF-8, including 883the @code{SELECTED_CHAR_KIND} and @code{NEW_LINE} intrinsic functions. 884 885@item Support for binary, octal and hexadecimal (BOZ) constants in the 886intrinsic functions @code{INT}, @code{REAL}, @code{CMPLX} and @code{DBLE}. 887 888@item Support for namelist variables with allocatable and pointer 889attribute and nonconstant length type parameter. 890 891@item 892@cindex array, constructors 893@cindex @code{[...]} 894Array constructors using square brackets. That is, @code{[...]} rather 895than @code{(/.../)}. Type-specification for array constructors like 896@code{(/ some-type :: ... /)}. 897 898@item Extensions to the specification and initialization expressions, 899including the support for intrinsics with real and complex arguments. 900 901@item Support for the asynchronous input/output. 902 903@item 904@cindex @code{FLUSH} statement 905@cindex statement, @code{FLUSH} 906@code{FLUSH} statement. 907 908@item 909@cindex @code{IOMSG=} specifier 910@code{IOMSG=} specifier for I/O statements. 911 912@item 913@cindex @code{ENUM} statement 914@cindex @code{ENUMERATOR} statement 915@cindex statement, @code{ENUM} 916@cindex statement, @code{ENUMERATOR} 917@opindex @code{fshort-enums} 918Support for the declaration of enumeration constants via the 919@code{ENUM} and @code{ENUMERATOR} statements. Interoperability with 920@command{gcc} is guaranteed also for the case where the 921@command{-fshort-enums} command line option is given. 922 923@item 924@cindex TR 15581 925TR 15581: 926@itemize 927@item 928@cindex @code{ALLOCATABLE} dummy arguments 929@code{ALLOCATABLE} dummy arguments. 930@item 931@cindex @code{ALLOCATABLE} function results 932@code{ALLOCATABLE} function results 933@item 934@cindex @code{ALLOCATABLE} components of derived types 935@code{ALLOCATABLE} components of derived types 936@end itemize 937 938@item 939@cindex @code{STREAM} I/O 940@cindex @code{ACCESS='STREAM'} I/O 941The @code{OPEN} statement supports the @code{ACCESS='STREAM'} specifier, 942allowing I/O without any record structure. 943 944@item 945Namelist input/output for internal files. 946 947@item Minor I/O features: Rounding during formatted output, using of 948a decimal comma instead of a decimal point, setting whether a plus sign 949should appear for positive numbers. On systems where @code{strtod} honours 950the rounding mode, the rounding mode is also supported for input. 951 952@item 953@cindex @code{PROTECTED} statement 954@cindex statement, @code{PROTECTED} 955The @code{PROTECTED} statement and attribute. 956 957@item 958@cindex @code{VALUE} statement 959@cindex statement, @code{VALUE} 960The @code{VALUE} statement and attribute. 961 962@item 963@cindex @code{VOLATILE} statement 964@cindex statement, @code{VOLATILE} 965The @code{VOLATILE} statement and attribute. 966 967@item 968@cindex @code{IMPORT} statement 969@cindex statement, @code{IMPORT} 970The @code{IMPORT} statement, allowing to import 971host-associated derived types. 972 973@item The intrinsic modules @code{ISO_FORTRAN_ENVIRONMENT} is supported, 974which contains parameters of the I/O units, storage sizes. Additionally, 975procedures for C interoperability are available in the @code{ISO_C_BINDING} 976module. 977 978@item 979@cindex @code{USE, INTRINSIC} statement 980@cindex statement, @code{USE, INTRINSIC} 981@cindex @code{ISO_FORTRAN_ENV} statement 982@cindex statement, @code{ISO_FORTRAN_ENV} 983@code{USE} statement with @code{INTRINSIC} and @code{NON_INTRINSIC} 984attribute; supported intrinsic modules: @code{ISO_FORTRAN_ENV}, 985@code{ISO_C_BINDING}, @code{OMP_LIB} and @code{OMP_LIB_KINDS}, 986and @code{OPENACC}. 987 988@item 989Renaming of operators in the @code{USE} statement. 990 991@end itemize 992 993 994@node Fortran 2008 status 995@section Fortran 2008 status 996 997The latest version of the Fortran standard is ISO/IEC 1539-1:2010, informally 998known as Fortran 2008. The official version is available from International 999Organization for Standardization (ISO) or its national member organizations. 1000The the final draft (FDIS) can be downloaded free of charge from 1001@url{http://www.nag.co.uk/@/sc22wg5/@/links.html}. Fortran is developed by the 1002Working Group 5 of Sub-Committee 22 of the Joint Technical Committee 1 of the 1003International Organization for Standardization and the International 1004Electrotechnical Commission (IEC). This group is known as 1005@uref{http://www.nag.co.uk/sc22wg5/, WG5}. 1006 1007The GNU Fortran compiler supports several of the new features of Fortran 2008; 1008the @uref{https://gcc.gnu.org/wiki/Fortran2008Status, wiki} has some information 1009about the current Fortran 2008 implementation status. In particular, the 1010following is implemented. 1011 1012@itemize 1013@item The @option{-std=f2008} option and support for the file extensions 1014@file{.f08} and @file{.F08}. 1015 1016@item The @code{OPEN} statement now supports the @code{NEWUNIT=} option, 1017which returns a unique file unit, thus preventing inadvertent use of the 1018same unit in different parts of the program. 1019 1020@item The @code{g0} format descriptor and unlimited format items. 1021 1022@item The mathematical intrinsics @code{ASINH}, @code{ACOSH}, @code{ATANH}, 1023@code{ERF}, @code{ERFC}, @code{GAMMA}, @code{LOG_GAMMA}, @code{BESSEL_J0}, 1024@code{BESSEL_J1}, @code{BESSEL_JN}, @code{BESSEL_Y0}, @code{BESSEL_Y1}, 1025@code{BESSEL_YN}, @code{HYPOT}, @code{NORM2}, and @code{ERFC_SCALED}. 1026 1027@item Using complex arguments with @code{TAN}, @code{SINH}, @code{COSH}, 1028@code{TANH}, @code{ASIN}, @code{ACOS}, and @code{ATAN} is now possible; 1029@code{ATAN}(@var{Y},@var{X}) is now an alias for @code{ATAN2}(@var{Y},@var{X}). 1030 1031@item Support of the @code{PARITY} intrinsic functions. 1032 1033@item The following bit intrinsics: @code{LEADZ} and @code{TRAILZ} for 1034counting the number of leading and trailing zero bits, @code{POPCNT} and 1035@code{POPPAR} for counting the number of one bits and returning the parity; 1036@code{BGE}, @code{BGT}, @code{BLE}, and @code{BLT} for bitwise comparisons; 1037@code{DSHIFTL} and @code{DSHIFTR} for combined left and right shifts, 1038@code{MASKL} and @code{MASKR} for simple left and right justified masks, 1039@code{MERGE_BITS} for a bitwise merge using a mask, @code{SHIFTA}, 1040@code{SHIFTL} and @code{SHIFTR} for shift operations, and the 1041transformational bit intrinsics @code{IALL}, @code{IANY} and @code{IPARITY}. 1042 1043@item Support of the @code{EXECUTE_COMMAND_LINE} intrinsic subroutine. 1044 1045@item Support for the @code{STORAGE_SIZE} intrinsic inquiry function. 1046 1047@item The @code{INT@{8,16,32@}} and @code{REAL@{32,64,128@}} kind type 1048parameters and the array-valued named constants @code{INTEGER_KINDS}, 1049@code{LOGICAL_KINDS}, @code{REAL_KINDS} and @code{CHARACTER_KINDS} of 1050the intrinsic module @code{ISO_FORTRAN_ENV}. 1051 1052@item The module procedures @code{C_SIZEOF} of the intrinsic module 1053@code{ISO_C_BINDINGS} and @code{COMPILER_VERSION} and @code{COMPILER_OPTIONS} 1054of @code{ISO_FORTRAN_ENV}. 1055 1056@item Coarray support for serial programs with @option{-fcoarray=single} flag 1057and experimental support for multiple images with the @option{-fcoarray=lib} 1058flag. 1059 1060@item Submodules are supported. It should noted that @code{MODULEs} do not 1061produce the smod file needed by the descendent @code{SUBMODULEs} unless they 1062contain at least one @code{MODULE PROCEDURE} interface. The reason for this is 1063that @code{SUBMODULEs} are useless without @code{MODULE PROCEDUREs}. See 1064http://j3-fortran.org/doc/meeting/207/15-209.txt for a discussion and a draft 1065interpretation. Adopting this interpretation has the advantage that code that 1066does not use submodules does not generate smod files. 1067 1068@item The @code{DO CONCURRENT} construct is supported. 1069 1070@item The @code{BLOCK} construct is supported. 1071 1072@item The @code{STOP} and the new @code{ERROR STOP} statements now 1073support all constant expressions. Both show the signals which were signaling 1074at termination. 1075 1076@item Support for the @code{CONTIGUOUS} attribute. 1077 1078@item Support for @code{ALLOCATE} with @code{MOLD}. 1079 1080@item Support for the @code{IMPURE} attribute for procedures, which 1081allows for @code{ELEMENTAL} procedures without the restrictions of 1082@code{PURE}. 1083 1084@item Null pointers (including @code{NULL()}) and not-allocated variables 1085can be used as actual argument to optional non-pointer, non-allocatable 1086dummy arguments, denoting an absent argument. 1087 1088@item Non-pointer variables with @code{TARGET} attribute can be used as 1089actual argument to @code{POINTER} dummies with @code{INTENT(IN)}. 1090 1091@item Pointers including procedure pointers and those in a derived 1092type (pointer components) can now be initialized by a target instead 1093of only by @code{NULL}. 1094 1095@item The @code{EXIT} statement (with construct-name) can be now be 1096used to leave not only the @code{DO} but also the @code{ASSOCIATE}, 1097@code{BLOCK}, @code{IF}, @code{SELECT CASE} and @code{SELECT TYPE} 1098constructs. 1099 1100@item Internal procedures can now be used as actual argument. 1101 1102@item Minor features: obsolesce diagnostics for @code{ENTRY} with 1103@option{-std=f2008}; a line may start with a semicolon; for internal 1104and module procedures @code{END} can be used instead of 1105@code{END SUBROUTINE} and @code{END FUNCTION}; @code{SELECTED_REAL_KIND} 1106now also takes a @code{RADIX} argument; intrinsic types are supported 1107for @code{TYPE}(@var{intrinsic-type-spec}); multiple type-bound procedures 1108can be declared in a single @code{PROCEDURE} statement; implied-shape 1109arrays are supported for named constants (@code{PARAMETER}). 1110@end itemize 1111 1112 1113 1114@node Fortran 2018 status 1115@section Status of Fortran 2018 support 1116 1117@itemize 1118@item ERROR STOP in a PURE procedure 1119An @code{ERROR STOP} statement is permitted in a @code{PURE} 1120procedure. 1121 1122@item IMPLICIT NONE with a spec-list 1123Support the @code{IMPLICIT NONE} statement with an 1124@code{implicit-none-spec-list}. 1125 1126@item Behavior of INQUIRE with the RECL= specifier 1127 1128The behavior of the @code{INQUIRE} statement with the @code{RECL=} 1129specifier now conforms to Fortran 2018. 1130 1131@end itemize 1132 1133 1134@subsection TS 29113 Status (Further Interoperability with C) 1135 1136GNU Fortran supports some of the new features of the Technical 1137Specification (TS) 29113 on Further Interoperability of Fortran with C. 1138The @uref{https://gcc.gnu.org/wiki/TS29113Status, wiki} has some information 1139about the current TS 29113 implementation status. In particular, the 1140following is implemented. 1141 1142See also @ref{Further Interoperability of Fortran with C}. 1143 1144@itemize 1145@item The @code{OPTIONAL} attribute is allowed for dummy arguments 1146of @code{BIND(C) procedures.} 1147 1148@item The @code{RANK} intrinsic is supported. 1149 1150@item GNU Fortran's implementation for variables with @code{ASYNCHRONOUS} 1151attribute is compatible with TS 29113. 1152 1153@item Assumed types (@code{TYPE(*)}). 1154 1155@item Assumed-rank (@code{DIMENSION(..)}). 1156 1157@item ISO_Fortran_binding (now in Fortran 2018 18.4) is implemented such that 1158conversion of the array descriptor for assumed type or assumed rank arrays is 1159done in the library. The include file ISO_Fortran_binding.h is can be found in 1160@code{~prefix/lib/gcc/$target/$version}. 1161@end itemize 1162 1163 1164 1165@subsection TS 18508 Status (Additional Parallel Features) 1166 1167GNU Fortran supports the following new features of the Technical 1168Specification 18508 on Additional Parallel Features in Fortran: 1169 1170@itemize 1171@item The new atomic ADD, CAS, FETCH and ADD/OR/XOR, OR and XOR intrinsics. 1172 1173@item The @code{CO_MIN} and @code{CO_MAX} and @code{SUM} reduction intrinsics. 1174And the @code{CO_BROADCAST} and @code{CO_REDUCE} intrinsic, except that those 1175do not support polymorphic types or types with allocatable, pointer or 1176polymorphic components. 1177 1178@item Events (@code{EVENT POST}, @code{EVENT WAIT}, @code{EVENT_QUERY}) 1179 1180@item Failed images (@code{FAIL IMAGE}, @code{IMAGE_STATUS}, 1181@code{FAILED_IMAGES}, @code{STOPPED_IMAGES}) 1182 1183@end itemize 1184 1185 1186@c --------------------------------------------------------------------- 1187@c Compiler Characteristics 1188@c --------------------------------------------------------------------- 1189 1190@node Compiler Characteristics 1191@chapter Compiler Characteristics 1192 1193This chapter describes certain characteristics of the GNU Fortran 1194compiler, that are not specified by the Fortran standard, but which 1195might in some way or another become visible to the programmer. 1196 1197@menu 1198* KIND Type Parameters:: 1199* Internal representation of LOGICAL variables:: 1200* Evaluation of logical expressions:: 1201* MAX and MIN intrinsics with REAL NaN arguments:: 1202* Thread-safety of the runtime library:: 1203* Data consistency and durability:: 1204* Files opened without an explicit ACTION= specifier:: 1205* File operations on symbolic links:: 1206* File format of unformatted sequential files:: 1207* Asynchronous I/O:: 1208@end menu 1209 1210 1211@node KIND Type Parameters 1212@section KIND Type Parameters 1213@cindex kind 1214 1215The @code{KIND} type parameters supported by GNU Fortran for the primitive 1216data types are: 1217 1218@table @code 1219 1220@item INTEGER 12211, 2, 4, 8*, 16*, default: 4** 1222 1223@item LOGICAL 12241, 2, 4, 8*, 16*, default: 4** 1225 1226@item REAL 12274, 8, 10*, 16*, default: 4*** 1228 1229@item COMPLEX 12304, 8, 10*, 16*, default: 4*** 1231 1232@item DOUBLE PRECISION 12334, 8, 10*, 16*, default: 8*** 1234 1235@item CHARACTER 12361, 4, default: 1 1237 1238@end table 1239 1240@noindent 1241* not available on all systems @* 1242** unless @option{-fdefault-integer-8} is used @* 1243*** unless @option{-fdefault-real-8} is used (see @ref{Fortran Dialect Options}) 1244 1245@noindent 1246The @code{KIND} value matches the storage size in bytes, except for 1247@code{COMPLEX} where the storage size is twice as much (or both real and 1248imaginary part are a real value of the given size). It is recommended to use 1249the @ref{SELECTED_CHAR_KIND}, @ref{SELECTED_INT_KIND} and 1250@ref{SELECTED_REAL_KIND} intrinsics or the @code{INT8}, @code{INT16}, 1251@code{INT32}, @code{INT64}, @code{REAL32}, @code{REAL64}, and @code{REAL128} 1252parameters of the @code{ISO_FORTRAN_ENV} module instead of the concrete values. 1253The available kind parameters can be found in the constant arrays 1254@code{CHARACTER_KINDS}, @code{INTEGER_KINDS}, @code{LOGICAL_KINDS} and 1255@code{REAL_KINDS} in the @ref{ISO_FORTRAN_ENV} module. For C interoperability, 1256the kind parameters of the @ref{ISO_C_BINDING} module should be used. 1257 1258 1259@node Internal representation of LOGICAL variables 1260@section Internal representation of LOGICAL variables 1261@cindex logical, variable representation 1262 1263The Fortran standard does not specify how variables of @code{LOGICAL} 1264type are represented, beyond requiring that @code{LOGICAL} variables 1265of default kind have the same storage size as default @code{INTEGER} 1266and @code{REAL} variables. The GNU Fortran internal representation is 1267as follows. 1268 1269A @code{LOGICAL(KIND=N)} variable is represented as an 1270@code{INTEGER(KIND=N)} variable, however, with only two permissible 1271values: @code{1} for @code{.TRUE.} and @code{0} for 1272@code{.FALSE.}. Any other integer value results in undefined behavior. 1273 1274See also @ref{Argument passing conventions} and @ref{Interoperability with C}. 1275 1276 1277@node Evaluation of logical expressions 1278@section Evaluation of logical expressions 1279 1280The Fortran standard does not require the compiler to evaluate all parts of an 1281expression, if they do not contribute to the final result. For logical 1282expressions with @code{.AND.} or @code{.OR.} operators, in particular, GNU 1283Fortran will optimize out function calls (even to impure functions) if the 1284result of the expression can be established without them. However, since not 1285all compilers do that, and such an optimization can potentially modify the 1286program flow and subsequent results, GNU Fortran throws warnings for such 1287situations with the @option{-Wfunction-elimination} flag. 1288 1289 1290@node MAX and MIN intrinsics with REAL NaN arguments 1291@section MAX and MIN intrinsics with REAL NaN arguments 1292@cindex MAX, MIN, NaN 1293 1294The Fortran standard does not specify what the result of the 1295@code{MAX} and @code{MIN} intrinsics are if one of the arguments is a 1296@code{NaN}. Accordingly, the GNU Fortran compiler does not specify 1297that either, as this allows for faster and more compact code to be 1298generated. If the programmer wishes to take some specific action in 1299case one of the arguments is a @code{NaN}, it is necessary to 1300explicitly test the arguments before calling @code{MAX} or @code{MIN}, 1301e.g. with the @code{IEEE_IS_NAN} function from the intrinsic module 1302@code{IEEE_ARITHMETIC}. 1303 1304 1305@node Thread-safety of the runtime library 1306@section Thread-safety of the runtime library 1307@cindex thread-safety, threads 1308 1309GNU Fortran can be used in programs with multiple threads, e.g.@: by 1310using OpenMP, by calling OS thread handling functions via the 1311@code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code 1312being called from a multi-threaded program. 1313 1314The GNU Fortran runtime library, (@code{libgfortran}), supports being 1315called concurrently from multiple threads with the following 1316exceptions. 1317 1318During library initialization, the C @code{getenv} function is used, 1319which need not be thread-safe. Similarly, the @code{getenv} 1320function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and 1321@code{GETENV} intrinsics. It is the responsibility of the user to 1322ensure that the environment is not being updated concurrently when any 1323of these actions are taking place. 1324 1325The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are 1326implemented with the @code{system} function, which need not be 1327thread-safe. It is the responsibility of the user to ensure that 1328@code{system} is not called concurrently. 1329 1330For platforms not supporting thread-safe POSIX functions, further 1331functionality might not be thread-safe. For details, please consult 1332the documentation for your operating system. 1333 1334The GNU Fortran runtime library uses various C library functions that 1335depend on the locale, such as @code{strtod} and @code{snprintf}. In 1336order to work correctly in locale-aware programs that set the locale 1337using @code{setlocale}, the locale is reset to the default ``C'' 1338locale while executing a formatted @code{READ} or @code{WRITE} 1339statement. On targets supporting the POSIX 2008 per-thread locale 1340functions (e.g. @code{newlocale}, @code{uselocale}, 1341@code{freelocale}), these are used and thus the global locale set 1342using @code{setlocale} or the per-thread locales in other threads are 1343not affected. However, on targets lacking this functionality, the 1344global LC_NUMERIC locale is set to ``C'' during the formatted I/O. 1345Thus, on such targets it's not safe to call @code{setlocale} 1346concurrently from another thread while a Fortran formatted I/O 1347operation is in progress. Also, other threads doing something 1348dependent on the LC_NUMERIC locale might not work correctly if a 1349formatted I/O operation is in progress in another thread. 1350 1351@node Data consistency and durability 1352@section Data consistency and durability 1353@cindex consistency, durability 1354 1355This section contains a brief overview of data and metadata 1356consistency and durability issues when doing I/O. 1357 1358With respect to durability, GNU Fortran makes no effort to ensure that 1359data is committed to stable storage. If this is required, the GNU 1360Fortran programmer can use the intrinsic @code{FNUM} to retrieve the 1361low level file descriptor corresponding to an open Fortran unit. Then, 1362using e.g. the @code{ISO_C_BINDING} feature, one can call the 1363underlying system call to flush dirty data to stable storage, such as 1364@code{fsync} on POSIX, @code{_commit} on MingW, or @code{fcntl(fd, 1365F_FULLSYNC, 0)} on Mac OS X. The following example shows how to call 1366fsync: 1367 1368@smallexample 1369 ! Declare the interface for POSIX fsync function 1370 interface 1371 function fsync (fd) bind(c,name="fsync") 1372 use iso_c_binding, only: c_int 1373 integer(c_int), value :: fd 1374 integer(c_int) :: fsync 1375 end function fsync 1376 end interface 1377 1378 ! Variable declaration 1379 integer :: ret 1380 1381 ! Opening unit 10 1382 open (10,file="foo") 1383 1384 ! ... 1385 ! Perform I/O on unit 10 1386 ! ... 1387 1388 ! Flush and sync 1389 flush(10) 1390 ret = fsync(fnum(10)) 1391 1392 ! Handle possible error 1393 if (ret /= 0) stop "Error calling FSYNC" 1394@end smallexample 1395 1396With respect to consistency, for regular files GNU Fortran uses 1397buffered I/O in order to improve performance. This buffer is flushed 1398automatically when full and in some other situations, e.g. when 1399closing a unit. It can also be explicitly flushed with the 1400@code{FLUSH} statement. Also, the buffering can be turned off with the 1401@code{GFORTRAN_UNBUFFERED_ALL} and 1402@code{GFORTRAN_UNBUFFERED_PRECONNECTED} environment variables. Special 1403files, such as terminals and pipes, are always unbuffered. Sometimes, 1404however, further things may need to be done in order to allow other 1405processes to see data that GNU Fortran has written, as follows. 1406 1407The Windows platform supports a relaxed metadata consistency model, 1408where file metadata is written to the directory lazily. This means 1409that, for instance, the @code{dir} command can show a stale size for a 1410file. One can force a directory metadata update by closing the unit, 1411or by calling @code{_commit} on the file descriptor. Note, though, 1412that @code{_commit} will force all dirty data to stable storage, which 1413is often a very slow operation. 1414 1415The Network File System (NFS) implements a relaxed consistency model 1416called open-to-close consistency. Closing a file forces dirty data and 1417metadata to be flushed to the server, and opening a file forces the 1418client to contact the server in order to revalidate cached 1419data. @code{fsync} will also force a flush of dirty data and metadata 1420to the server. Similar to @code{open} and @code{close}, acquiring and 1421releasing @code{fcntl} file locks, if the server supports them, will 1422also force cache validation and flushing dirty data and metadata. 1423 1424 1425@node Files opened without an explicit ACTION= specifier 1426@section Files opened without an explicit ACTION= specifier 1427@cindex open, action 1428 1429The Fortran standard says that if an @code{OPEN} statement is executed 1430without an explicit @code{ACTION=} specifier, the default value is 1431processor dependent. GNU Fortran behaves as follows: 1432 1433@enumerate 1434@item Attempt to open the file with @code{ACTION='READWRITE'} 1435@item If that fails, try to open with @code{ACTION='READ'} 1436@item If that fails, try to open with @code{ACTION='WRITE'} 1437@item If that fails, generate an error 1438@end enumerate 1439 1440 1441@node File operations on symbolic links 1442@section File operations on symbolic links 1443@cindex file, symbolic link 1444 1445This section documents the behavior of GNU Fortran for file operations on 1446symbolic links, on systems that support them. 1447 1448@itemize 1449 1450@item Results of INQUIRE statements of the ``inquire by file'' form will 1451relate to the target of the symbolic link. For example, 1452@code{INQUIRE(FILE="foo",EXIST=ex)} will set @var{ex} to @var{.true.} if 1453@var{foo} is a symbolic link pointing to an existing file, and @var{.false.} 1454if @var{foo} points to an non-existing file (``dangling'' symbolic link). 1455 1456@item Using the @code{OPEN} statement with a @code{STATUS="NEW"} specifier 1457on a symbolic link will result in an error condition, whether the symbolic 1458link points to an existing target or is dangling. 1459 1460@item If a symbolic link was connected, using the @code{CLOSE} statement 1461with a @code{STATUS="DELETE"} specifier will cause the symbolic link itself 1462to be deleted, not its target. 1463 1464@end itemize 1465 1466@node File format of unformatted sequential files 1467@section File format of unformatted sequential files 1468@cindex file, unformatted sequential 1469@cindex unformatted sequential 1470@cindex sequential, unformatted 1471@cindex record marker 1472@cindex subrecord 1473 1474Unformatted sequential files are stored as logical records using 1475record markers. Each logical record consists of one of more 1476subrecords. 1477 1478Each subrecord consists of a leading record marker, the data written 1479by the user program, and a trailing record marker. The record markers 1480are four-byte integers by default, and eight-byte integers if the 1481@option{-fmax-subrecord-length=8} option (which exists for backwards 1482compability only) is in effect. 1483 1484The representation of the record markers is that of unformatted files 1485given with the @option{-fconvert} option, the @ref{CONVERT specifier} 1486in an open statement or the @ref{GFORTRAN_CONVERT_UNIT} environment 1487variable. 1488 1489The maximum number of bytes of user data in a subrecord is 2147483639 1490(2 GiB - 9) for a four-byte record marker. This limit can be lowered 1491with the @option{-fmax-subrecord-length} option, altough this is 1492rarely useful. If the length of a logical record exceeds this limit, 1493the data is distributed among several subrecords. 1494 1495The absolute of the number stored in the record markers is the number 1496of bytes of user data in the corresponding subrecord. If the leading 1497record marker of a subrecord contains a negative number, another 1498subrecord follows the current one. If the trailing record marker 1499contains a negative number, then there is a preceding subrecord. 1500 1501In the most simple case, with only one subrecord per logical record, 1502both record markers contain the number of bytes of user data in the 1503record. 1504 1505The format for unformatted sequential data can be duplicated using 1506unformatted stream, as shown in the example program for an unformatted 1507record containing a single subrecord: 1508 1509@smallexample 1510program main 1511 use iso_fortran_env, only: int32 1512 implicit none 1513 integer(int32) :: i 1514 real, dimension(10) :: a, b 1515 call random_number(a) 1516 open (10,file='test.dat',form='unformatted',access='stream') 1517 inquire (iolength=i) a 1518 write (10) i, a, i 1519 close (10) 1520 open (10,file='test.dat',form='unformatted') 1521 read (10) b 1522 if (all (a == b)) print *,'success!' 1523end program main 1524@end smallexample 1525 1526@node Asynchronous I/O 1527@section Asynchronous I/O 1528@cindex input/output, asynchronous 1529@cindex asynchronous I/O 1530 1531Asynchronous I/O is supported if the program is linked against the 1532POSIX thread library. If that is not the case, all I/O is performed 1533as synchronous. On systems which do not support pthread condition 1534variables, such as AIX, I/O is also performed as synchronous. 1535 1536On some systems, such as Darwin or Solaris, the POSIX thread library 1537is always linked in, so asynchronous I/O is always performed. On other 1538sytems, such as Linux, it is necessary to specify @option{-pthread}, 1539@option{-lpthread} or @option{-fopenmp} during the linking step. 1540 1541@c --------------------------------------------------------------------- 1542@c Extensions 1543@c --------------------------------------------------------------------- 1544 1545@c Maybe this chapter should be merged with the 'Standards' section, 1546@c whenever that is written :-) 1547 1548@node Extensions 1549@chapter Extensions 1550@cindex extensions 1551 1552The two sections below detail the extensions to standard Fortran that are 1553implemented in GNU Fortran, as well as some of the popular or 1554historically important extensions that are not (or not yet) implemented. 1555For the latter case, we explain the alternatives available to GNU Fortran 1556users, including replacement by standard-conforming code or GNU 1557extensions. 1558 1559@menu 1560* Extensions implemented in GNU Fortran:: 1561* Extensions not implemented in GNU Fortran:: 1562@end menu 1563 1564 1565@node Extensions implemented in GNU Fortran 1566@section Extensions implemented in GNU Fortran 1567@cindex extensions, implemented 1568 1569GNU Fortran implements a number of extensions over standard Fortran. 1570This chapter contains information on their syntax and meaning. There 1571are currently two categories of GNU Fortran extensions, those that 1572provide functionality beyond that provided by any standard, and those 1573that are supported by GNU Fortran purely for backward compatibility 1574with legacy compilers. By default, @option{-std=gnu} allows the 1575compiler to accept both types of extensions, but to warn about the use 1576of the latter. Specifying either @option{-std=f95}, 1577@option{-std=f2003}, @option{-std=f2008}, or @option{-std=f2018} 1578disables both types of extensions, and @option{-std=legacy} allows 1579both without warning. The special compile flag @option{-fdec} enables 1580additional compatibility extensions along with those enabled by 1581@option{-std=legacy}. 1582 1583@menu 1584* Old-style kind specifications:: 1585* Old-style variable initialization:: 1586* Extensions to namelist:: 1587* X format descriptor without count field:: 1588* Commas in FORMAT specifications:: 1589* Missing period in FORMAT specifications:: 1590* Default widths for F@comma{} G and I format descriptors:: 1591* I/O item lists:: 1592* @code{Q} exponent-letter:: 1593* BOZ literal constants:: 1594* Real array indices:: 1595* Unary operators:: 1596* Implicitly convert LOGICAL and INTEGER values:: 1597* Hollerith constants support:: 1598* Character conversion:: 1599* Cray pointers:: 1600* CONVERT specifier:: 1601* OpenMP:: 1602* OpenACC:: 1603* Argument list functions:: 1604* Read/Write after EOF marker:: 1605* STRUCTURE and RECORD:: 1606* UNION and MAP:: 1607* Type variants for integer intrinsics:: 1608* AUTOMATIC and STATIC attributes:: 1609* Extended math intrinsics:: 1610* Form feed as whitespace:: 1611* TYPE as an alias for PRINT:: 1612* %LOC as an rvalue:: 1613* .XOR. operator:: 1614* Bitwise logical operators:: 1615* Extended I/O specifiers:: 1616* Legacy PARAMETER statements:: 1617* Default exponents:: 1618@end menu 1619 1620@node Old-style kind specifications 1621@subsection Old-style kind specifications 1622@cindex kind, old-style 1623 1624GNU Fortran allows old-style kind specifications in declarations. These 1625look like: 1626@smallexample 1627 TYPESPEC*size x,y,z 1628@end smallexample 1629@noindent 1630where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL}, 1631etc.), and where @code{size} is a byte count corresponding to the 1632storage size of a valid kind for that type. (For @code{COMPLEX} 1633variables, @code{size} is the total size of the real and imaginary 1634parts.) The statement then declares @code{x}, @code{y} and @code{z} to 1635be of type @code{TYPESPEC} with the appropriate kind. This is 1636equivalent to the standard-conforming declaration 1637@smallexample 1638 TYPESPEC(k) x,y,z 1639@end smallexample 1640@noindent 1641where @code{k} is the kind parameter suitable for the intended precision. As 1642kind parameters are implementation-dependent, use the @code{KIND}, 1643@code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve 1644the correct value, for instance @code{REAL*8 x} can be replaced by: 1645@smallexample 1646INTEGER, PARAMETER :: dbl = KIND(1.0d0) 1647REAL(KIND=dbl) :: x 1648@end smallexample 1649 1650@node Old-style variable initialization 1651@subsection Old-style variable initialization 1652 1653GNU Fortran allows old-style initialization of variables of the 1654form: 1655@smallexample 1656 INTEGER i/1/,j/2/ 1657 REAL x(2,2) /3*0.,1./ 1658@end smallexample 1659The syntax for the initializers is as for the @code{DATA} statement, but 1660unlike in a @code{DATA} statement, an initializer only applies to the 1661variable immediately preceding the initialization. In other words, 1662something like @code{INTEGER I,J/2,3/} is not valid. This style of 1663initialization is only allowed in declarations without double colons 1664(@code{::}); the double colons were introduced in Fortran 90, which also 1665introduced a standard syntax for initializing variables in type 1666declarations. 1667 1668Examples of standard-conforming code equivalent to the above example 1669are: 1670@smallexample 1671! Fortran 90 1672 INTEGER :: i = 1, j = 2 1673 REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x)) 1674! Fortran 77 1675 INTEGER i, j 1676 REAL x(2,2) 1677 DATA i/1/, j/2/, x/3*0.,1./ 1678@end smallexample 1679 1680Note that variables which are explicitly initialized in declarations 1681or in @code{DATA} statements automatically acquire the @code{SAVE} 1682attribute. 1683 1684@node Extensions to namelist 1685@subsection Extensions to namelist 1686@cindex Namelist 1687 1688GNU Fortran fully supports the Fortran 95 standard for namelist I/O 1689including array qualifiers, substrings and fully qualified derived types. 1690The output from a namelist write is compatible with namelist read. The 1691output has all names in upper case and indentation to column 1 after the 1692namelist name. Two extensions are permitted: 1693 1694Old-style use of @samp{$} instead of @samp{&} 1695@smallexample 1696$MYNML 1697 X(:)%Y(2) = 1.0 2.0 3.0 1698 CH(1:4) = "abcd" 1699$END 1700@end smallexample 1701 1702It should be noted that the default terminator is @samp{/} rather than 1703@samp{&END}. 1704 1705Querying of the namelist when inputting from stdin. After at least 1706one space, entering @samp{?} sends to stdout the namelist name and the names of 1707the variables in the namelist: 1708@smallexample 1709 ? 1710 1711&mynml 1712 x 1713 x%y 1714 ch 1715&end 1716@end smallexample 1717 1718Entering @samp{=?} outputs the namelist to stdout, as if 1719@code{WRITE(*,NML = mynml)} had been called: 1720@smallexample 1721=? 1722 1723&MYNML 1724 X(1)%Y= 0.000000 , 1.000000 , 0.000000 , 1725 X(2)%Y= 0.000000 , 2.000000 , 0.000000 , 1726 X(3)%Y= 0.000000 , 3.000000 , 0.000000 , 1727 CH=abcd, / 1728@end smallexample 1729 1730To aid this dialog, when input is from stdin, errors send their 1731messages to stderr and execution continues, even if @code{IOSTAT} is set. 1732 1733@code{PRINT} namelist is permitted. This causes an error if 1734@option{-std=f95} is used. 1735@smallexample 1736PROGRAM test_print 1737 REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/) 1738 NAMELIST /mynml/ x 1739 PRINT mynml 1740END PROGRAM test_print 1741@end smallexample 1742 1743Expanded namelist reads are permitted. This causes an error if 1744@option{-std=f95} is used. In the following example, the first element 1745of the array will be given the value 0.00 and the two succeeding 1746elements will be given the values 1.00 and 2.00. 1747@smallexample 1748&MYNML 1749 X(1,1) = 0.00 , 1.00 , 2.00 1750/ 1751@end smallexample 1752 1753When writing a namelist, if no @code{DELIM=} is specified, by default a 1754double quote is used to delimit character strings. If -std=F95, F2003, 1755or F2008, etc, the delim status is set to 'none'. Defaulting to 1756quotes ensures that namelists with character strings can be subsequently 1757read back in accurately. 1758 1759@node X format descriptor without count field 1760@subsection @code{X} format descriptor without count field 1761 1762To support legacy codes, GNU Fortran permits the count field of the 1763@code{X} edit descriptor in @code{FORMAT} statements to be omitted. 1764When omitted, the count is implicitly assumed to be one. 1765 1766@smallexample 1767 PRINT 10, 2, 3 176810 FORMAT (I1, X, I1) 1769@end smallexample 1770 1771@node Commas in FORMAT specifications 1772@subsection Commas in @code{FORMAT} specifications 1773 1774To support legacy codes, GNU Fortran allows the comma separator 1775to be omitted immediately before and after character string edit 1776descriptors in @code{FORMAT} statements. A comma with no following format 1777decriptor is permited if the @option{-fdec-blank-format-item} is given on 1778the command line. This is considered non-conforming code and is 1779discouraged. 1780 1781@smallexample 1782 PRINT 10, 2, 3 178310 FORMAT ('FOO='I1' BAR='I2) 1784 print 20, 5, 6 178520 FORMAT (I3, I3,) 1786@end smallexample 1787 1788 1789@node Missing period in FORMAT specifications 1790@subsection Missing period in @code{FORMAT} specifications 1791 1792To support legacy codes, GNU Fortran allows missing periods in format 1793specifications if and only if @option{-std=legacy} is given on the 1794command line. This is considered non-conforming code and is 1795discouraged. 1796 1797@smallexample 1798 REAL :: value 1799 READ(*,10) value 180010 FORMAT ('F4') 1801@end smallexample 1802 1803@node Default widths for F@comma{} G and I format descriptors 1804@subsection Default widths for @code{F}, @code{G} and @code{I} format descriptors 1805 1806To support legacy codes, GNU Fortran allows width to be omitted from format 1807specifications if and only if @option{-fdec-format-defaults} is given on the 1808command line. Default widths will be used. This is considered non-conforming 1809code and is discouraged. 1810 1811@smallexample 1812 REAL :: value1 1813 INTEGER :: value2 1814 WRITE(*,10) value1, value1, value2 181510 FORMAT ('F, G, I') 1816@end smallexample 1817 1818 1819@node I/O item lists 1820@subsection I/O item lists 1821@cindex I/O item lists 1822 1823To support legacy codes, GNU Fortran allows the input item list 1824of the @code{READ} statement, and the output item lists of the 1825@code{WRITE} and @code{PRINT} statements, to start with a comma. 1826 1827@node @code{Q} exponent-letter 1828@subsection @code{Q} exponent-letter 1829@cindex @code{Q} exponent-letter 1830 1831GNU Fortran accepts real literal constants with an exponent-letter 1832of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted 1833as a @code{REAL(16)} entity on targets that support this type. If 1834the target does not support @code{REAL(16)} but has a @code{REAL(10)} 1835type, then the real-literal-constant will be interpreted as a 1836@code{REAL(10)} entity. In the absence of @code{REAL(16)} and 1837@code{REAL(10)}, an error will occur. 1838 1839@node BOZ literal constants 1840@subsection BOZ literal constants 1841@cindex BOZ literal constants 1842 1843Besides decimal constants, Fortran also supports binary (@code{b}), 1844octal (@code{o}) and hexadecimal (@code{z}) integer constants. The 1845syntax is: @samp{prefix quote digits quote}, were the prefix is 1846either @code{b}, @code{o} or @code{z}, quote is either @code{'} or 1847@code{"} and the digits are @code{0} or @code{1} for binary, 1848between @code{0} and @code{7} for octal, and between @code{0} and 1849@code{F} for hexadecimal. (Example: @code{b'01011101'}.) 1850 1851Up to Fortran 95, BOZ literal constants were only allowed to initialize 1852integer variables in DATA statements. Since Fortran 2003 BOZ literal 1853constants are also allowed as actual arguments to the @code{REAL}, 1854@code{DBLE}, @code{INT} and @code{CMPLX} intrinsic functions. 1855The BOZ literal constant is simply a string of bits, which is padded 1856or truncated as needed, during conversion to a numeric type. The 1857Fortran standard states that the treatment of the sign bit is processor 1858dependent. Gfortran interprets the sign bit as a user would expect. 1859 1860As a deprecated extension, GNU Fortran allows hexadecimal BOZ literal 1861constants to be specified using the @code{X} prefix. That the BOZ literal 1862constant can also be specified by adding a suffix to the string, for 1863example, @code{Z'ABC'} and @code{'ABC'X} are equivalent. Additionally, 1864as extension, BOZ literals are permitted in some contexts outside of 1865@code{DATA} and the intrinsic functions listed in the Fortran standard. 1866Use @option{-fallow-invalid-boz} to enable the extension. 1867 1868@node Real array indices 1869@subsection Real array indices 1870@cindex array, indices of type real 1871 1872As an extension, GNU Fortran allows the use of @code{REAL} expressions 1873or variables as array indices. 1874 1875@node Unary operators 1876@subsection Unary operators 1877@cindex operators, unary 1878 1879As an extension, GNU Fortran allows unary plus and unary minus operators 1880to appear as the second operand of binary arithmetic operators without 1881the need for parenthesis. 1882 1883@smallexample 1884 X = Y * -Z 1885@end smallexample 1886 1887@node Implicitly convert LOGICAL and INTEGER values 1888@subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values 1889@cindex conversion, to integer 1890@cindex conversion, to logical 1891 1892As an extension for backwards compatibility with other compilers, GNU 1893Fortran allows the implicit conversion of @code{LOGICAL} values to 1894@code{INTEGER} values and vice versa. When converting from a 1895@code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as 1896zero, and @code{.TRUE.} is interpreted as one. When converting from 1897@code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as 1898@code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}. 1899 1900@smallexample 1901 LOGICAL :: l 1902 l = 1 1903@end smallexample 1904@smallexample 1905 INTEGER :: i 1906 i = .TRUE. 1907@end smallexample 1908 1909However, there is no implicit conversion of @code{INTEGER} values in 1910@code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values 1911in I/O operations. 1912 1913@node Hollerith constants support 1914@subsection Hollerith constants support 1915@cindex Hollerith constants 1916 1917GNU Fortran supports Hollerith constants in assignments, @code{DATA} 1918statements, function and subroutine arguments. A Hollerith constant is 1919written as a string of characters preceded by an integer constant 1920indicating the character count, and the letter @code{H} or 1921@code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER}, 1922@code{REAL}, or @code{COMPLEX}), @code{LOGICAL} or @code{CHARACTER} variable. 1923The constant will be padded with spaces or truncated to fit the size of 1924the variable in which it is stored. 1925 1926Examples of valid uses of Hollerith constants: 1927@smallexample 1928 complex*16 x(2) 1929 data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/ 1930 x(1) = 16HABCDEFGHIJKLMNOP 1931 call foo (4h abc) 1932@end smallexample 1933 1934Examples of Hollerith constants: 1935@smallexample 1936 integer*4 a 1937 a = 0H ! Invalid, at least one character is needed. 1938 a = 4HAB12 ! Valid 1939 a = 8H12345678 ! Valid, but the Hollerith constant will be truncated. 1940 a = 3Hxyz ! Valid, but the Hollerith constant will be padded. 1941@end smallexample 1942 1943In general, Hollerith constants were used to provide a rudimentary 1944facility for handling character strings in early Fortran compilers, 1945prior to the introduction of @code{CHARACTER} variables in Fortran 77; 1946in those cases, the standard-compliant equivalent is to convert the 1947program to use proper character strings. On occasion, there may be a 1948case where the intent is specifically to initialize a numeric variable 1949with a given byte sequence. In these cases, the same result can be 1950obtained by using the @code{TRANSFER} statement, as in this example. 1951@smallexample 1952 integer(kind=4) :: a 1953 a = transfer ("abcd", a) ! equivalent to: a = 4Habcd 1954@end smallexample 1955 1956The use of the @option{-fdec} option extends support of Hollerith constants 1957to comparisons: 1958@smallexample 1959 integer*4 a 1960 a = 4hABCD 1961 if (a .ne. 4habcd) then 1962 write(*,*) "no match" 1963 end if 1964@end smallexample 1965 1966Supported types are numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}), 1967and @code{CHARACTER}. 1968 1969@node Character conversion 1970@subsection Character conversion 1971@cindex conversion, to character 1972 1973Allowing character literals to be used in a similar way to Hollerith constants 1974is a non-standard extension. This feature is enabled using 1975-fdec-char-conversions and only applies to character literals of @code{kind=1}. 1976 1977Character literals can be used in @code{DATA} statements and assignments with 1978numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}) or @code{LOGICAL} 1979variables. Like Hollerith constants they are copied byte-wise fashion. The 1980constant will be padded with spaces or truncated to fit the size of the 1981variable in which it is stored. 1982 1983Examples: 1984@smallexample 1985 integer*4 x 1986 data x / 'abcd' / 1987 1988 x = 'A' ! Will be padded. 1989 x = 'ab1234' ! Will be truncated. 1990@end smallexample 1991 1992 1993@node Cray pointers 1994@subsection Cray pointers 1995@cindex pointer, Cray 1996 1997Cray pointers are part of a non-standard extension that provides a 1998C-like pointer in Fortran. This is accomplished through a pair of 1999variables: an integer "pointer" that holds a memory address, and a 2000"pointee" that is used to dereference the pointer. 2001 2002Pointer/pointee pairs are declared in statements of the form: 2003@smallexample 2004 pointer ( <pointer> , <pointee> ) 2005@end smallexample 2006or, 2007@smallexample 2008 pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ... 2009@end smallexample 2010The pointer is an integer that is intended to hold a memory address. 2011The pointee may be an array or scalar. 2012If an assumed-size array is permitted within the scoping unit, a 2013pointee can be an assumed-size array. 2014That is, the last dimension may be left unspecified by using a @code{*} 2015in place of a value. A pointee cannot be an assumed shape array. 2016No space is allocated for the pointee. 2017 2018The pointee may have its type declared before or after the pointer 2019statement, and its array specification (if any) may be declared 2020before, during, or after the pointer statement. The pointer may be 2021declared as an integer prior to the pointer statement. However, some 2022machines have default integer sizes that are different than the size 2023of a pointer, and so the following code is not portable: 2024@smallexample 2025 integer ipt 2026 pointer (ipt, iarr) 2027@end smallexample 2028If a pointer is declared with a kind that is too small, the compiler 2029will issue a warning; the resulting binary will probably not work 2030correctly, because the memory addresses stored in the pointers may be 2031truncated. It is safer to omit the first line of the above example; 2032if explicit declaration of ipt's type is omitted, then the compiler 2033will ensure that ipt is an integer variable large enough to hold a 2034pointer. 2035 2036Pointer arithmetic is valid with Cray pointers, but it is not the same 2037as C pointer arithmetic. Cray pointers are just ordinary integers, so 2038the user is responsible for determining how many bytes to add to a 2039pointer in order to increment it. Consider the following example: 2040@smallexample 2041 real target(10) 2042 real pointee(10) 2043 pointer (ipt, pointee) 2044 ipt = loc (target) 2045 ipt = ipt + 1 2046@end smallexample 2047The last statement does not set @code{ipt} to the address of 2048@code{target(1)}, as it would in C pointer arithmetic. Adding @code{1} 2049to @code{ipt} just adds one byte to the address stored in @code{ipt}. 2050 2051Any expression involving the pointee will be translated to use the 2052value stored in the pointer as the base address. 2053 2054To get the address of elements, this extension provides an intrinsic 2055function @code{LOC()}. The @code{LOC()} function is equivalent to the 2056@code{&} operator in C, except the address is cast to an integer type: 2057@smallexample 2058 real ar(10) 2059 pointer(ipt, arpte(10)) 2060 real arpte 2061 ipt = loc(ar) ! Makes arpte is an alias for ar 2062 arpte(1) = 1.0 ! Sets ar(1) to 1.0 2063@end smallexample 2064The pointer can also be set by a call to the @code{MALLOC} intrinsic 2065(see @ref{MALLOC}). 2066 2067Cray pointees often are used to alias an existing variable. For 2068example: 2069@smallexample 2070 integer target(10) 2071 integer iarr(10) 2072 pointer (ipt, iarr) 2073 ipt = loc(target) 2074@end smallexample 2075As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for 2076@code{target}. The optimizer, however, will not detect this aliasing, so 2077it is unsafe to use @code{iarr} and @code{target} simultaneously. Using 2078a pointee in any way that violates the Fortran aliasing rules or 2079assumptions is illegal. It is the user's responsibility to avoid doing 2080this; the compiler works under the assumption that no such aliasing 2081occurs. 2082 2083Cray pointers will work correctly when there is no aliasing (i.e., when 2084they are used to access a dynamically allocated block of memory), and 2085also in any routine where a pointee is used, but any variable with which 2086it shares storage is not used. Code that violates these rules may not 2087run as the user intends. This is not a bug in the optimizer; any code 2088that violates the aliasing rules is illegal. (Note that this is not 2089unique to GNU Fortran; any Fortran compiler that supports Cray pointers 2090will ``incorrectly'' optimize code with illegal aliasing.) 2091 2092There are a number of restrictions on the attributes that can be applied 2093to Cray pointers and pointees. Pointees may not have the 2094@code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY}, 2095@code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers 2096may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET}, 2097@code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor 2098may they be function results. Pointees may not occur in more than one 2099pointer statement. A pointee cannot be a pointer. Pointees cannot occur 2100in equivalence, common, or data statements. 2101 2102A Cray pointer may also point to a function or a subroutine. For 2103example, the following excerpt is valid: 2104@smallexample 2105 implicit none 2106 external sub 2107 pointer (subptr,subpte) 2108 external subpte 2109 subptr = loc(sub) 2110 call subpte() 2111 [...] 2112 subroutine sub 2113 [...] 2114 end subroutine sub 2115@end smallexample 2116 2117A pointer may be modified during the course of a program, and this 2118will change the location to which the pointee refers. However, when 2119pointees are passed as arguments, they are treated as ordinary 2120variables in the invoked function. Subsequent changes to the pointer 2121will not change the base address of the array that was passed. 2122 2123@node CONVERT specifier 2124@subsection @code{CONVERT} specifier 2125@cindex @code{CONVERT} specifier 2126 2127GNU Fortran allows the conversion of unformatted data between little- 2128and big-endian representation to facilitate moving of data 2129between different systems. The conversion can be indicated with 2130the @code{CONVERT} specifier on the @code{OPEN} statement. 2131@xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying 2132the data format via an environment variable. 2133 2134Valid values for @code{CONVERT} are: 2135@itemize @w{} 2136@item @code{CONVERT='NATIVE'} Use the native format. This is the default. 2137@item @code{CONVERT='SWAP'} Swap between little- and big-endian. 2138@item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation 2139for unformatted files. 2140@item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for 2141unformatted files. 2142@end itemize 2143 2144Using the option could look like this: 2145@smallexample 2146 open(file='big.dat',form='unformatted',access='sequential', & 2147 convert='big_endian') 2148@end smallexample 2149 2150The value of the conversion can be queried by using 2151@code{INQUIRE(CONVERT=ch)}. The values returned are 2152@code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}. 2153 2154@code{CONVERT} works between big- and little-endian for 2155@code{INTEGER} values of all supported kinds and for @code{REAL} 2156on IEEE systems of kinds 4 and 8. Conversion between different 2157``extended double'' types on different architectures such as 2158m68k and x86_64, which GNU Fortran 2159supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will 2160probably not work. 2161 2162@emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT 2163environment variable will override the CONVERT specifier in the 2164open statement}. This is to give control over data formats to 2165users who do not have the source code of their program available. 2166 2167Using anything but the native representation for unformatted data 2168carries a significant speed overhead. If speed in this area matters 2169to you, it is best if you use this only for data that needs to be 2170portable. 2171 2172@node OpenMP 2173@subsection OpenMP 2174@cindex OpenMP 2175 2176OpenMP (Open Multi-Processing) is an application programming 2177interface (API) that supports multi-platform shared memory 2178multiprocessing programming in C/C++ and Fortran on many 2179architectures, including Unix and Microsoft Windows platforms. 2180It consists of a set of compiler directives, library routines, 2181and environment variables that influence run-time behavior. 2182 2183GNU Fortran strives to be compatible to the 2184@uref{http://openmp.org/wp/openmp-specifications/, 2185OpenMP Application Program Interface v4.5}. 2186 2187To enable the processing of the OpenMP directive @code{!$omp} in 2188free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp} 2189directives in fixed form; the @code{!$} conditional compilation sentinels 2190in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels 2191in fixed form, @command{gfortran} needs to be invoked with the 2192@option{-fopenmp}. This also arranges for automatic linking of the 2193GNU Offloading and Multi Processing Runtime Library 2194@ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime 2195Library}. 2196 2197The OpenMP Fortran runtime library routines are provided both in a 2198form of a Fortran 90 module named @code{omp_lib} and in a form of 2199a Fortran @code{include} file named @file{omp_lib.h}. 2200 2201An example of a parallelized loop taken from Appendix A.1 of 2202the OpenMP Application Program Interface v2.5: 2203@smallexample 2204SUBROUTINE A1(N, A, B) 2205 INTEGER I, N 2206 REAL B(N), A(N) 2207!$OMP PARALLEL DO !I is private by default 2208 DO I=2,N 2209 B(I) = (A(I) + A(I-1)) / 2.0 2210 ENDDO 2211!$OMP END PARALLEL DO 2212END SUBROUTINE A1 2213@end smallexample 2214 2215Please note: 2216@itemize 2217@item 2218@option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays 2219will be allocated on the stack. When porting existing code to OpenMP, 2220this may lead to surprising results, especially to segmentation faults 2221if the stacksize is limited. 2222 2223@item 2224On glibc-based systems, OpenMP enabled applications cannot be statically 2225linked due to limitations of the underlying pthreads-implementation. It 2226might be possible to get a working solution if 2227@command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added 2228to the command line. However, this is not supported by @command{gcc} and 2229thus not recommended. 2230@end itemize 2231 2232@node OpenACC 2233@subsection OpenACC 2234@cindex OpenACC 2235 2236OpenACC is an application programming interface (API) that supports 2237offloading of code to accelerator devices. It consists of a set of 2238compiler directives, library routines, and environment variables that 2239influence run-time behavior. 2240 2241GNU Fortran strives to be compatible to the 2242@uref{http://www.openacc.org/, OpenACC Application Programming 2243Interface v2.6}. 2244 2245To enable the processing of the OpenACC directive @code{!$acc} in 2246free-form source code; the @code{c$acc}, @code{*$acc} and @code{!$acc} 2247directives in fixed form; the @code{!$} conditional compilation 2248sentinels in free form; and the @code{c$}, @code{*$} and @code{!$} 2249sentinels in fixed form, @command{gfortran} needs to be invoked with 2250the @option{-fopenacc}. This also arranges for automatic linking of 2251the GNU Offloading and Multi Processing Runtime Library 2252@ref{Top,,libgomp,libgomp,GNU Offloading and Multi Processing Runtime 2253Library}. 2254 2255The OpenACC Fortran runtime library routines are provided both in a 2256form of a Fortran 90 module named @code{openacc} and in a form of a 2257Fortran @code{include} file named @file{openacc_lib.h}. 2258 2259@node Argument list functions 2260@subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC} 2261@cindex argument list functions 2262@cindex @code{%VAL} 2263@cindex @code{%REF} 2264@cindex @code{%LOC} 2265 2266GNU Fortran supports argument list functions @code{%VAL}, @code{%REF} 2267and @code{%LOC} statements, for backward compatibility with g77. 2268It is recommended that these should be used only for code that is 2269accessing facilities outside of GNU Fortran, such as operating system 2270or windowing facilities. It is best to constrain such uses to isolated 2271portions of a program--portions that deal specifically and exclusively 2272with low-level, system-dependent facilities. Such portions might well 2273provide a portable interface for use by the program as a whole, but are 2274themselves not portable, and should be thoroughly tested each time they 2275are rebuilt using a new compiler or version of a compiler. 2276 2277@code{%VAL} passes a scalar argument by value, @code{%REF} passes it by 2278reference and @code{%LOC} passes its memory location. Since gfortran 2279already passes scalar arguments by reference, @code{%REF} is in effect 2280a do-nothing. @code{%LOC} has the same effect as a Fortran pointer. 2281 2282An example of passing an argument by value to a C subroutine foo.: 2283@smallexample 2284C 2285C prototype void foo_ (float x); 2286C 2287 external foo 2288 real*4 x 2289 x = 3.14159 2290 call foo (%VAL (x)) 2291 end 2292@end smallexample 2293 2294For details refer to the g77 manual 2295@uref{https://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}. 2296 2297Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the 2298GNU Fortran testsuite are worth a look. 2299 2300@node Read/Write after EOF marker 2301@subsection Read/Write after EOF marker 2302@cindex @code{EOF} 2303@cindex @code{BACKSPACE} 2304@cindex @code{REWIND} 2305 2306Some legacy codes rely on allowing @code{READ} or @code{WRITE} after the 2307EOF file marker in order to find the end of a file. GNU Fortran normally 2308rejects these codes with a run-time error message and suggests the user 2309consider @code{BACKSPACE} or @code{REWIND} to properly position 2310the file before the EOF marker. As an extension, the run-time error may 2311be disabled using -std=legacy. 2312 2313 2314@node STRUCTURE and RECORD 2315@subsection @code{STRUCTURE} and @code{RECORD} 2316@cindex @code{STRUCTURE} 2317@cindex @code{RECORD} 2318 2319Record structures are a pre-Fortran-90 vendor extension to create 2320user-defined aggregate data types. Support for record structures in GNU 2321Fortran can be enabled with the @option{-fdec-structure} compile flag. 2322If you have a choice, you should instead use Fortran 90's ``derived types'', 2323which have a different syntax. 2324 2325In many cases, record structures can easily be converted to derived types. 2326To convert, replace @code{STRUCTURE /}@var{structure-name}@code{/} 2327by @code{TYPE} @var{type-name}. Additionally, replace 2328@code{RECORD /}@var{structure-name}@code{/} by 2329@code{TYPE(}@var{type-name}@code{)}. Finally, in the component access, 2330replace the period (@code{.}) by the percent sign (@code{%}). 2331 2332Here is an example of code using the non portable record structure syntax: 2333 2334@example 2335! Declaring a structure named ``item'' and containing three fields: 2336! an integer ID, an description string and a floating-point price. 2337STRUCTURE /item/ 2338 INTEGER id 2339 CHARACTER(LEN=200) description 2340 REAL price 2341END STRUCTURE 2342 2343! Define two variables, an single record of type ``item'' 2344! named ``pear'', and an array of items named ``store_catalog'' 2345RECORD /item/ pear, store_catalog(100) 2346 2347! We can directly access the fields of both variables 2348pear.id = 92316 2349pear.description = "juicy D'Anjou pear" 2350pear.price = 0.15 2351store_catalog(7).id = 7831 2352store_catalog(7).description = "milk bottle" 2353store_catalog(7).price = 1.2 2354 2355! We can also manipulate the whole structure 2356store_catalog(12) = pear 2357print *, store_catalog(12) 2358@end example 2359 2360@noindent 2361This code can easily be rewritten in the Fortran 90 syntax as following: 2362 2363@example 2364! ``STRUCTURE /name/ ... END STRUCTURE'' becomes 2365! ``TYPE name ... END TYPE'' 2366TYPE item 2367 INTEGER id 2368 CHARACTER(LEN=200) description 2369 REAL price 2370END TYPE 2371 2372! ``RECORD /name/ variable'' becomes ``TYPE(name) variable'' 2373TYPE(item) pear, store_catalog(100) 2374 2375! Instead of using a dot (.) to access fields of a record, the 2376! standard syntax uses a percent sign (%) 2377pear%id = 92316 2378pear%description = "juicy D'Anjou pear" 2379pear%price = 0.15 2380store_catalog(7)%id = 7831 2381store_catalog(7)%description = "milk bottle" 2382store_catalog(7)%price = 1.2 2383 2384! Assignments of a whole variable do not change 2385store_catalog(12) = pear 2386print *, store_catalog(12) 2387@end example 2388 2389@noindent 2390GNU Fortran implements STRUCTURES like derived types with the following 2391rules and exceptions: 2392 2393@itemize @bullet 2394@item Structures act like derived types with the @code{SEQUENCE} attribute. 2395Otherwise they may contain no specifiers. 2396 2397@item Structures may contain a special field with the name @code{%FILL}. 2398This will create an anonymous component which cannot be accessed but occupies 2399space just as if a component of the same type was declared in its place, useful 2400for alignment purposes. As an example, the following structure will consist 2401of at least sixteen bytes: 2402 2403@smallexample 2404structure /padded/ 2405 character(4) start 2406 character(8) %FILL 2407 character(4) end 2408end structure 2409@end smallexample 2410 2411@item Structures may share names with other symbols. For example, the following 2412is invalid for derived types, but valid for structures: 2413 2414@smallexample 2415structure /header/ 2416 ! ... 2417end structure 2418record /header/ header 2419@end smallexample 2420 2421@item Structure types may be declared nested within another parent structure. 2422The syntax is: 2423@smallexample 2424structure /type-name/ 2425 ... 2426 structure [/<type-name>/] <field-list> 2427... 2428@end smallexample 2429 2430The type name may be ommitted, in which case the structure type itself is 2431anonymous, and other structures of the same type cannot be instantiated. The 2432following shows some examples: 2433 2434@example 2435structure /appointment/ 2436 ! nested structure definition: app_time is an array of two 'time' 2437 structure /time/ app_time (2) 2438 integer(1) hour, minute 2439 end structure 2440 character(10) memo 2441end structure 2442 2443! The 'time' structure is still usable 2444record /time/ now 2445now = time(5, 30) 2446 2447... 2448 2449structure /appointment/ 2450 ! anonymous nested structure definition 2451 structure start, end 2452 integer(1) hour, minute 2453 end structure 2454 character(10) memo 2455end structure 2456@end example 2457 2458@item Structures may contain @code{UNION} blocks. For more detail see the 2459section on @ref{UNION and MAP}. 2460 2461@item Structures support old-style initialization of components, like 2462those described in @ref{Old-style variable initialization}. For array 2463initializers, an initializer may contain a repeat specification of the form 2464@code{<literal-integer> * <constant-initializer>}. The value of the integer 2465indicates the number of times to repeat the constant initializer when expanding 2466the initializer list. 2467@end itemize 2468 2469@node UNION and MAP 2470@subsection @code{UNION} and @code{MAP} 2471@cindex @code{UNION} 2472@cindex @code{MAP} 2473 2474Unions are an old vendor extension which were commonly used with the 2475non-standard @ref{STRUCTURE and RECORD} extensions. Use of @code{UNION} and 2476@code{MAP} is automatically enabled with @option{-fdec-structure}. 2477 2478A @code{UNION} declaration occurs within a structure; within the definition of 2479each union is a number of @code{MAP} blocks. Each @code{MAP} shares storage 2480with its sibling maps (in the same union), and the size of the union is the 2481size of the largest map within it, just as with unions in C. The major 2482difference is that component references do not indicate which union or map the 2483component is in (the compiler gets to figure that out). 2484 2485Here is a small example: 2486@smallexample 2487structure /myunion/ 2488union 2489 map 2490 character(2) w0, w1, w2 2491 end map 2492 map 2493 character(6) long 2494 end map 2495end union 2496end structure 2497 2498record /myunion/ rec 2499! After this assignment... 2500rec.long = 'hello!' 2501 2502! The following is true: 2503! rec.w0 === 'he' 2504! rec.w1 === 'll' 2505! rec.w2 === 'o!' 2506@end smallexample 2507 2508The two maps share memory, and the size of the union is ultimately six bytes: 2509 2510@example 25110 1 2 3 4 5 6 Byte offset 2512------------------------------- 2513| | | | | | | 2514------------------------------- 2515 2516^ W0 ^ W1 ^ W2 ^ 2517 \-------/ \-------/ \-------/ 2518 2519^ LONG ^ 2520 \---------------------------/ 2521@end example 2522 2523Following is an example mirroring the layout of an Intel x86_64 register: 2524 2525@example 2526structure /reg/ 2527 union ! U0 ! rax 2528 map 2529 character(16) rx 2530 end map 2531 map 2532 character(8) rh ! rah 2533 union ! U1 2534 map 2535 character(8) rl ! ral 2536 end map 2537 map 2538 character(8) ex ! eax 2539 end map 2540 map 2541 character(4) eh ! eah 2542 union ! U2 2543 map 2544 character(4) el ! eal 2545 end map 2546 map 2547 character(4) x ! ax 2548 end map 2549 map 2550 character(2) h ! ah 2551 character(2) l ! al 2552 end map 2553 end union 2554 end map 2555 end union 2556 end map 2557 end union 2558end structure 2559record /reg/ a 2560 2561! After this assignment... 2562a.rx = 'AAAAAAAA.BBB.C.D' 2563 2564! The following is true: 2565a.rx === 'AAAAAAAA.BBB.C.D' 2566a.rh === 'AAAAAAAA' 2567a.rl === '.BBB.C.D' 2568a.ex === '.BBB.C.D' 2569a.eh === '.BBB' 2570a.el === '.C.D' 2571a.x === '.C.D' 2572a.h === '.C' 2573a.l === '.D' 2574@end example 2575 2576@node Type variants for integer intrinsics 2577@subsection Type variants for integer intrinsics 2578@cindex intrinsics, integer 2579 2580Similar to the D/C prefixes to real functions to specify the input/output 2581types, GNU Fortran offers B/I/J/K prefixes to integer functions for 2582compatibility with DEC programs. The types implied by each are: 2583 2584@example 2585@code{B} - @code{INTEGER(kind=1)} 2586@code{I} - @code{INTEGER(kind=2)} 2587@code{J} - @code{INTEGER(kind=4)} 2588@code{K} - @code{INTEGER(kind=8)} 2589@end example 2590 2591GNU Fortran supports these with the flag @option{-fdec-intrinsic-ints}. 2592Intrinsics for which prefixed versions are available and in what form are noted 2593in @ref{Intrinsic Procedures}. The complete list of supported intrinsics is 2594here: 2595 2596@multitable @columnfractions .2 .2 .2 .2 .2 2597 2598@headitem Intrinsic @tab B @tab I @tab J @tab K 2599 2600@item @code{@ref{ABS}} 2601 @tab @code{BABS} @tab @code{IIABS} @tab @code{JIABS} @tab @code{KIABS} 2602@item @code{@ref{BTEST}} 2603 @tab @code{BBTEST} @tab @code{BITEST} @tab @code{BJTEST} @tab @code{BKTEST} 2604@item @code{@ref{IAND}} 2605 @tab @code{BIAND} @tab @code{IIAND} @tab @code{JIAND} @tab @code{KIAND} 2606@item @code{@ref{IBCLR}} 2607 @tab @code{BBCLR} @tab @code{IIBCLR} @tab @code{JIBCLR} @tab @code{KIBCLR} 2608@item @code{@ref{IBITS}} 2609 @tab @code{BBITS} @tab @code{IIBITS} @tab @code{JIBITS} @tab @code{KIBITS} 2610@item @code{@ref{IBSET}} 2611 @tab @code{BBSET} @tab @code{IIBSET} @tab @code{JIBSET} @tab @code{KIBSET} 2612@item @code{@ref{IEOR}} 2613 @tab @code{BIEOR} @tab @code{IIEOR} @tab @code{JIEOR} @tab @code{KIEOR} 2614@item @code{@ref{IOR}} 2615 @tab @code{BIOR} @tab @code{IIOR} @tab @code{JIOR} @tab @code{KIOR} 2616@item @code{@ref{ISHFT}} 2617 @tab @code{BSHFT} @tab @code{IISHFT} @tab @code{JISHFT} @tab @code{KISHFT} 2618@item @code{@ref{ISHFTC}} 2619 @tab @code{BSHFTC} @tab @code{IISHFTC} @tab @code{JISHFTC} @tab @code{KISHFTC} 2620@item @code{@ref{MOD}} 2621 @tab @code{BMOD} @tab @code{IMOD} @tab @code{JMOD} @tab @code{KMOD} 2622@item @code{@ref{NOT}} 2623 @tab @code{BNOT} @tab @code{INOT} @tab @code{JNOT} @tab @code{KNOT} 2624@item @code{@ref{REAL}} 2625 @tab @code{--} @tab @code{FLOATI} @tab @code{FLOATJ} @tab @code{FLOATK} 2626@end multitable 2627 2628@node AUTOMATIC and STATIC attributes 2629@subsection @code{AUTOMATIC} and @code{STATIC} attributes 2630@cindex variable attributes 2631@cindex @code{AUTOMATIC} 2632@cindex @code{STATIC} 2633 2634With @option{-fdec-static} GNU Fortran supports the DEC extended attributes 2635@code{STATIC} and @code{AUTOMATIC} to provide explicit specification of entity 2636storage. These follow the syntax of the Fortran standard @code{SAVE} attribute. 2637 2638@code{STATIC} is exactly equivalent to @code{SAVE}, and specifies that 2639an entity should be allocated in static memory. As an example, @code{STATIC} 2640local variables will retain their values across multiple calls to a function. 2641 2642Entities marked @code{AUTOMATIC} will be stack automatic whenever possible. 2643@code{AUTOMATIC} is the default for local variables smaller than 2644@option{-fmax-stack-var-size}, unless @option{-fno-automatic} is given. This 2645attribute overrides @option{-fno-automatic}, @option{-fmax-stack-var-size}, and 2646blanket @code{SAVE} statements. 2647 2648 2649Examples: 2650 2651@example 2652subroutine f 2653 integer, automatic :: i ! automatic variable 2654 integer x, y ! static variables 2655 save 2656 ... 2657endsubroutine 2658@end example 2659@example 2660subroutine f 2661 integer a, b, c, x, y, z 2662 static :: x 2663 save y 2664 automatic z, c 2665 ! a, b, c, and z are automatic 2666 ! x and y are static 2667endsubroutine 2668@end example 2669@example 2670! Compiled with -fno-automatic 2671subroutine f 2672 integer a, b, c, d 2673 automatic :: a 2674 ! a is automatic; b, c, and d are static 2675endsubroutine 2676@end example 2677 2678@node Extended math intrinsics 2679@subsection Extended math intrinsics 2680@cindex intrinsics, math 2681@cindex intrinsics, trigonometric functions 2682 2683GNU Fortran supports an extended list of mathematical intrinsics with the 2684compile flag @option{-fdec-math} for compatability with legacy code. 2685These intrinsics are described fully in @ref{Intrinsic Procedures} where it is 2686noted that they are extensions and should be avoided whenever possible. 2687 2688Specifically, @option{-fdec-math} enables the @ref{COTAN} intrinsic, and 2689trigonometric intrinsics which accept or produce values in degrees instead of 2690radians. Here is a summary of the new intrinsics: 2691 2692@multitable @columnfractions .5 .5 2693@headitem Radians @tab Degrees 2694@item @code{@ref{ACOS}} @tab @code{@ref{ACOSD}}* 2695@item @code{@ref{ASIN}} @tab @code{@ref{ASIND}}* 2696@item @code{@ref{ATAN}} @tab @code{@ref{ATAND}}* 2697@item @code{@ref{ATAN2}} @tab @code{@ref{ATAN2D}}* 2698@item @code{@ref{COS}} @tab @code{@ref{COSD}}* 2699@item @code{@ref{COTAN}}* @tab @code{@ref{COTAND}}* 2700@item @code{@ref{SIN}} @tab @code{@ref{SIND}}* 2701@item @code{@ref{TAN}} @tab @code{@ref{TAND}}* 2702@end multitable 2703 2704* Enabled with @option{-fdec-math}. 2705 2706For advanced users, it may be important to know the implementation of these 2707functions. They are simply wrappers around the standard radian functions, which 2708have more accurate builtin versions. These functions convert their arguments 2709(or results) to degrees (or radians) by taking the value modulus 360 (or 2*pi) 2710and then multiplying it by a constant radian-to-degree (or degree-to-radian) 2711factor, as appropriate. The factor is computed at compile-time as 180/pi (or 2712pi/180). 2713 2714@node Form feed as whitespace 2715@subsection Form feed as whitespace 2716@cindex form feed whitespace 2717 2718Historically, legacy compilers allowed insertion of form feed characters ('\f', 2719ASCII 0xC) at the beginning of lines for formatted output to line printers, 2720though the Fortran standard does not mention this. GNU Fortran supports the 2721interpretation of form feed characters in source as whitespace for 2722compatibility. 2723 2724@node TYPE as an alias for PRINT 2725@subsection TYPE as an alias for PRINT 2726@cindex type alias print 2727For compatibility, GNU Fortran will interpret @code{TYPE} statements as 2728@code{PRINT} statements with the flag @option{-fdec}. With this flag asserted, 2729the following two examples are equivalent: 2730 2731@smallexample 2732TYPE *, 'hello world' 2733@end smallexample 2734 2735@smallexample 2736PRINT *, 'hello world' 2737@end smallexample 2738 2739@node %LOC as an rvalue 2740@subsection %LOC as an rvalue 2741@cindex LOC 2742Normally @code{%LOC} is allowed only in parameter lists. However the intrinsic 2743function @code{LOC} does the same thing, and is usable as the right-hand-side of 2744assignments. For compatibility, GNU Fortran supports the use of @code{%LOC} as 2745an alias for the builtin @code{LOC} with @option{-std=legacy}. With this 2746feature enabled the following two examples are equivalent: 2747 2748@smallexample 2749integer :: i, l 2750l = %loc(i) 2751call sub(l) 2752@end smallexample 2753 2754@smallexample 2755integer :: i 2756call sub(%loc(i)) 2757@end smallexample 2758 2759@node .XOR. operator 2760@subsection .XOR. operator 2761@cindex operators, xor 2762 2763GNU Fortran supports @code{.XOR.} as a logical operator with @code{-std=legacy} 2764for compatibility with legacy code. @code{.XOR.} is equivalent to 2765@code{.NEQV.}. That is, the output is true if and only if the inputs differ. 2766 2767@node Bitwise logical operators 2768@subsection Bitwise logical operators 2769@cindex logical, bitwise 2770 2771With @option{-fdec}, GNU Fortran relaxes the type constraints on 2772logical operators to allow integer operands, and performs the corresponding 2773bitwise operation instead. This flag is for compatibility only, and should be 2774avoided in new code. Consider: 2775 2776@smallexample 2777 INTEGER :: i, j 2778 i = z'33' 2779 j = z'cc' 2780 print *, i .AND. j 2781@end smallexample 2782 2783In this example, compiled with @option{-fdec}, GNU Fortran will 2784replace the @code{.AND.} operation with a call to the intrinsic 2785@code{@ref{IAND}} function, yielding the bitwise-and of @code{i} and @code{j}. 2786 2787Note that this conversion will occur if at least one operand is of integral 2788type. As a result, a logical operand will be converted to an integer when the 2789other operand is an integer in a logical operation. In this case, 2790@code{.TRUE.} is converted to @code{1} and @code{.FALSE.} to @code{0}. 2791 2792Here is the mapping of logical operator to bitwise intrinsic used with 2793@option{-fdec}: 2794 2795@multitable @columnfractions .25 .25 .5 2796@headitem Operator @tab Intrinsic @tab Bitwise operation 2797@item @code{.NOT.} @tab @code{@ref{NOT}} @tab complement 2798@item @code{.AND.} @tab @code{@ref{IAND}} @tab intersection 2799@item @code{.OR.} @tab @code{@ref{IOR}} @tab union 2800@item @code{.NEQV.} @tab @code{@ref{IEOR}} @tab exclusive or 2801@item @code{.EQV.} @tab @code{@ref{NOT}(@ref{IEOR})} @tab complement of exclusive or 2802@end multitable 2803 2804@node Extended I/O specifiers 2805@subsection Extended I/O specifiers 2806@cindex @code{CARRIAGECONTROL} 2807@cindex @code{READONLY} 2808@cindex @code{SHARE} 2809@cindex @code{SHARED} 2810@cindex @code{NOSHARED} 2811@cindex I/O specifiers 2812 2813GNU Fortran supports the additional legacy I/O specifiers 2814@code{CARRIAGECONTROL}, @code{READONLY}, and @code{SHARE} with the 2815compile flag @option{-fdec}, for compatibility. 2816 2817@table @code 2818@item CARRIAGECONTROL 2819The @code{CARRIAGECONTROL} specifier allows a user to control line 2820termination settings between output records for an I/O unit. The specifier has 2821no meaning for readonly files. When @code{CARRAIGECONTROL} is specified upon 2822opening a unit for formatted writing, the exact @code{CARRIAGECONTROL} setting 2823determines what characters to write between output records. The syntax is: 2824 2825@smallexample 2826OPEN(..., CARRIAGECONTROL=cc) 2827@end smallexample 2828 2829Where @emph{cc} is a character expression that evaluates to one of the 2830following values: 2831 2832@multitable @columnfractions .2 .8 2833@item @code{'LIST'} @tab One line feed between records (default) 2834@item @code{'FORTRAN'} @tab Legacy interpretation of the first character (see below) 2835@item @code{'NONE'} @tab No separator between records 2836@end multitable 2837 2838With @code{CARRIAGECONTROL='FORTRAN'}, when a record is written, the first 2839character of the input record is not written, and instead determines the output 2840record separator as follows: 2841 2842@multitable @columnfractions .3 .3 .4 2843@headitem Leading character @tab Meaning @tab Output separating character(s) 2844@item @code{'+'} @tab Overprinting @tab Carriage return only 2845@item @code{'-'} @tab New line @tab Line feed and carriage return 2846@item @code{'0'} @tab Skip line @tab Two line feeds and carriage return 2847@item @code{'1'} @tab New page @tab Form feed and carriage return 2848@item @code{'$'} @tab Prompting @tab Line feed (no carriage return) 2849@item @code{CHAR(0)} @tab Overprinting (no advance) @tab None 2850@end multitable 2851 2852@item READONLY 2853The @code{READONLY} specifier may be given upon opening a unit, and is 2854equivalent to specifying @code{ACTION='READ'}, except that the file may not be 2855deleted on close (i.e. @code{CLOSE} with @code{STATUS="DELETE"}). The syntax 2856is: 2857 2858@smallexample 2859@code{OPEN(..., READONLY)} 2860@end smallexample 2861 2862@item SHARE 2863The @code{SHARE} specifier allows system-level locking on a unit upon opening 2864it for controlled access from multiple processes/threads. The @code{SHARE} 2865specifier has several forms: 2866 2867@smallexample 2868OPEN(..., SHARE=sh) 2869OPEN(..., SHARED) 2870OPEN(..., NOSHARED) 2871@end smallexample 2872 2873Where @emph{sh} in the first form is a character expression that evaluates to 2874a value as seen in the table below. The latter two forms are aliases 2875for particular values of @emph{sh}: 2876 2877@multitable @columnfractions .3 .3 .4 2878@headitem Explicit form @tab Short form @tab Meaning 2879@item @code{SHARE='DENYRW'} @tab @code{NOSHARED} @tab Exclusive (write) lock 2880@item @code{SHARE='DENYNONE'} @tab @code{SHARED} @tab Shared (read) lock 2881@end multitable 2882 2883In general only one process may hold an exclusive (write) lock for a given file 2884at a time, whereas many processes may hold shared (read) locks for the same 2885file. 2886 2887The behavior of locking may vary with your operating system. On POSIX systems, 2888locking is implemented with @code{fcntl}. Consult your corresponding operating 2889system's manual pages for further details. Locking via @code{SHARE=} is not 2890supported on other systems. 2891 2892@end table 2893 2894@node Legacy PARAMETER statements 2895@subsection Legacy PARAMETER statements 2896@cindex PARAMETER 2897 2898For compatibility, GNU Fortran supports legacy PARAMETER statements without 2899parentheses with @option{-std=legacy}. A warning is emitted if used with 2900@option{-std=gnu}, and an error is acknowledged with a real Fortran standard 2901flag (@option{-std=f95}, etc...). These statements take the following form: 2902 2903@smallexample 2904implicit real (E) 2905parameter e = 2.718282 2906real c 2907parameter c = 3.0e8 2908@end smallexample 2909 2910@node Default exponents 2911@subsection Default exponents 2912@cindex exponent 2913 2914For compatibility, GNU Fortran supports a default exponent of zero in real 2915constants with @option{-fdec}. For example, @code{9e} would be 2916interpreted as @code{9e0}, rather than an error. 2917 2918 2919@node Extensions not implemented in GNU Fortran 2920@section Extensions not implemented in GNU Fortran 2921@cindex extensions, not implemented 2922 2923The long history of the Fortran language, its wide use and broad 2924userbase, the large number of different compiler vendors and the lack of 2925some features crucial to users in the first standards have lead to the 2926existence of a number of important extensions to the language. While 2927some of the most useful or popular extensions are supported by the GNU 2928Fortran compiler, not all existing extensions are supported. This section 2929aims at listing these extensions and offering advice on how best make 2930code that uses them running with the GNU Fortran compiler. 2931 2932@c More can be found here: 2933@c -- https://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html 2934@c -- the list of Fortran and libgfortran bugs closed as WONTFIX: 2935@c http://tinyurl.com/2u4h5y 2936 2937@menu 2938* ENCODE and DECODE statements:: 2939* Variable FORMAT expressions:: 2940@c * TYPE and ACCEPT I/O Statements:: 2941@c * DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers:: 2942@c * Omitted arguments in procedure call:: 2943* Alternate complex function syntax:: 2944* Volatile COMMON blocks:: 2945* OPEN( ... NAME=):: 2946* Q edit descriptor:: 2947@end menu 2948 2949@node ENCODE and DECODE statements 2950@subsection @code{ENCODE} and @code{DECODE} statements 2951@cindex @code{ENCODE} 2952@cindex @code{DECODE} 2953 2954GNU Fortran does not support the @code{ENCODE} and @code{DECODE} 2955statements. These statements are best replaced by @code{READ} and 2956@code{WRITE} statements involving internal files (@code{CHARACTER} 2957variables and arrays), which have been part of the Fortran standard since 2958Fortran 77. For example, replace a code fragment like 2959 2960@smallexample 2961 INTEGER*1 LINE(80) 2962 REAL A, B, C 2963c ... Code that sets LINE 2964 DECODE (80, 9000, LINE) A, B, C 2965 9000 FORMAT (1X, 3(F10.5)) 2966@end smallexample 2967 2968@noindent 2969with the following: 2970 2971@smallexample 2972 CHARACTER(LEN=80) LINE 2973 REAL A, B, C 2974c ... Code that sets LINE 2975 READ (UNIT=LINE, FMT=9000) A, B, C 2976 9000 FORMAT (1X, 3(F10.5)) 2977@end smallexample 2978 2979Similarly, replace a code fragment like 2980 2981@smallexample 2982 INTEGER*1 LINE(80) 2983 REAL A, B, C 2984c ... Code that sets A, B and C 2985 ENCODE (80, 9000, LINE) A, B, C 2986 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) 2987@end smallexample 2988 2989@noindent 2990with the following: 2991 2992@smallexample 2993 CHARACTER(LEN=80) LINE 2994 REAL A, B, C 2995c ... Code that sets A, B and C 2996 WRITE (UNIT=LINE, FMT=9000) A, B, C 2997 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) 2998@end smallexample 2999 3000 3001@node Variable FORMAT expressions 3002@subsection Variable @code{FORMAT} expressions 3003@cindex @code{FORMAT} 3004 3005A variable @code{FORMAT} expression is format statement which includes 3006angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU 3007Fortran does not support this legacy extension. The effect of variable 3008format expressions can be reproduced by using the more powerful (and 3009standard) combination of internal output and string formats. For example, 3010replace a code fragment like this: 3011 3012@smallexample 3013 WRITE(6,20) INT1 3014 20 FORMAT(I<N+1>) 3015@end smallexample 3016 3017@noindent 3018with the following: 3019 3020@smallexample 3021c Variable declaration 3022 CHARACTER(LEN=20) FMT 3023c 3024c Other code here... 3025c 3026 WRITE(FMT,'("(I", I0, ")")') N+1 3027 WRITE(6,FMT) INT1 3028@end smallexample 3029 3030@noindent 3031or with: 3032 3033@smallexample 3034c Variable declaration 3035 CHARACTER(LEN=20) FMT 3036c 3037c Other code here... 3038c 3039 WRITE(FMT,*) N+1 3040 WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1 3041@end smallexample 3042 3043 3044@node Alternate complex function syntax 3045@subsection Alternate complex function syntax 3046@cindex Complex function 3047 3048Some Fortran compilers, including @command{g77}, let the user declare 3049complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as 3050well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy 3051extensions. @command{gfortran} accepts the latter form, which is more 3052common, but not the former. 3053 3054 3055@node Volatile COMMON blocks 3056@subsection Volatile @code{COMMON} blocks 3057@cindex @code{VOLATILE} 3058@cindex @code{COMMON} 3059 3060Some Fortran compilers, including @command{g77}, let the user declare 3061@code{COMMON} with the @code{VOLATILE} attribute. This is 3062invalid standard Fortran syntax and is not supported by 3063@command{gfortran}. Note that @command{gfortran} accepts 3064@code{VOLATILE} variables in @code{COMMON} blocks since revision 4.3. 3065 3066 3067@node OPEN( ... NAME=) 3068@subsection @code{OPEN( ... NAME=)} 3069@cindex @code{NAME} 3070 3071Some Fortran compilers, including @command{g77}, let the user declare 3072@code{OPEN( ... NAME=)}. This is 3073invalid standard Fortran syntax and is not supported by 3074@command{gfortran}. @code{OPEN( ... NAME=)} should be replaced 3075with @code{OPEN( ... FILE=)}. 3076 3077@node Q edit descriptor 3078@subsection @code{Q} edit descriptor 3079@cindex @code{Q} edit descriptor 3080 3081Some Fortran compilers provide the @code{Q} edit descriptor, which 3082transfers the number of characters left within an input record into an 3083integer variable. 3084 3085A direct replacement of the @code{Q} edit descriptor is not available 3086in @command{gfortran}. How to replicate its functionality using 3087standard-conforming code depends on what the intent of the original 3088code is. 3089 3090Options to replace @code{Q} may be to read the whole line into a 3091character variable and then counting the number of non-blank 3092characters left using @code{LEN_TRIM}. Another method may be to use 3093formatted stream, read the data up to the position where the @code{Q} 3094descriptor occurred, use @code{INQUIRE} to get the file position, 3095count the characters up to the next @code{NEW_LINE} and then start 3096reading from the position marked previously. 3097 3098 3099@c --------------------------------------------------------------------- 3100@c --------------------------------------------------------------------- 3101@c Mixed-Language Programming 3102@c --------------------------------------------------------------------- 3103 3104@node Mixed-Language Programming 3105@chapter Mixed-Language Programming 3106@cindex Interoperability 3107@cindex Mixed-language programming 3108 3109@menu 3110* Interoperability with C:: 3111* GNU Fortran Compiler Directives:: 3112* Non-Fortran Main Program:: 3113* Naming and argument-passing conventions:: 3114@end menu 3115 3116This chapter is about mixed-language interoperability, but also applies 3117if one links Fortran code compiled by different compilers. In most cases, 3118use of the C Binding features of the Fortran 2003 standard is sufficient, 3119and their use is highly recommended. 3120 3121 3122@node Interoperability with C 3123@section Interoperability with C 3124 3125@menu 3126* Intrinsic Types:: 3127* Derived Types and struct:: 3128* Interoperable Global Variables:: 3129* Interoperable Subroutines and Functions:: 3130* Working with Pointers:: 3131* Further Interoperability of Fortran with C:: 3132@end menu 3133 3134Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a 3135standardized way to generate procedure and derived-type 3136declarations and global variables which are interoperable with C 3137(ISO/IEC 9899:1999). The @code{bind(C)} attribute has been added 3138to inform the compiler that a symbol shall be interoperable with C; 3139also, some constraints are added. Note, however, that not 3140all C features have a Fortran equivalent or vice versa. For instance, 3141neither C's unsigned integers nor C's functions with variable number 3142of arguments have an equivalent in Fortran. 3143 3144Note that array dimensions are reversely ordered in C and that arrays in 3145C always start with index 0 while in Fortran they start by default with 31461. Thus, an array declaration @code{A(n,m)} in Fortran matches 3147@code{A[m][n]} in C and accessing the element @code{A(i,j)} matches 3148@code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]}; 3149assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}). 3150 3151@node Intrinsic Types 3152@subsection Intrinsic Types 3153 3154In order to ensure that exactly the same variable type and kind is used 3155in C and Fortran, the named constants shall be used which are defined in the 3156@code{ISO_C_BINDING} intrinsic module. That module contains named constants 3157for kind parameters and character named constants for the escape sequences 3158in C. For a list of the constants, see @ref{ISO_C_BINDING}. 3159 3160For logical types, please note that the Fortran standard only guarantees 3161interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind 3162logicals and C99 defines that @code{true} has the value 1 and @code{false} 3163the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL} 3164(with any kind parameter) gives an undefined result. (Passing other integer 3165values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the 3166integer is explicitly or implicitly casted to @code{_Bool}.) 3167 3168 3169 3170@node Derived Types and struct 3171@subsection Derived Types and struct 3172 3173For compatibility of derived types with @code{struct}, one needs to use 3174the @code{BIND(C)} attribute in the type declaration. For instance, the 3175following type declaration 3176 3177@smallexample 3178 USE ISO_C_BINDING 3179 TYPE, BIND(C) :: myType 3180 INTEGER(C_INT) :: i1, i2 3181 INTEGER(C_SIGNED_CHAR) :: i3 3182 REAL(C_DOUBLE) :: d1 3183 COMPLEX(C_FLOAT_COMPLEX) :: c1 3184 CHARACTER(KIND=C_CHAR) :: str(5) 3185 END TYPE 3186@end smallexample 3187 3188matches the following @code{struct} declaration in C 3189 3190@smallexample 3191 struct @{ 3192 int i1, i2; 3193 /* Note: "char" might be signed or unsigned. */ 3194 signed char i3; 3195 double d1; 3196 float _Complex c1; 3197 char str[5]; 3198 @} myType; 3199@end smallexample 3200 3201Derived types with the C binding attribute shall not have the @code{sequence} 3202attribute, type parameters, the @code{extends} attribute, nor type-bound 3203procedures. Every component must be of interoperable type and kind and may not 3204have the @code{pointer} or @code{allocatable} attribute. The names of the 3205components are irrelevant for interoperability. 3206 3207As there exist no direct Fortran equivalents, neither unions nor structs 3208with bit field or variable-length array members are interoperable. 3209 3210@node Interoperable Global Variables 3211@subsection Interoperable Global Variables 3212 3213Variables can be made accessible from C using the C binding attribute, 3214optionally together with specifying a binding name. Those variables 3215have to be declared in the declaration part of a @code{MODULE}, 3216be of interoperable type, and have neither the @code{pointer} nor 3217the @code{allocatable} attribute. 3218 3219@smallexample 3220 MODULE m 3221 USE myType_module 3222 USE ISO_C_BINDING 3223 integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag 3224 type(myType), bind(C) :: tp 3225 END MODULE 3226@end smallexample 3227 3228Here, @code{_MyProject_flags} is the case-sensitive name of the variable 3229as seen from C programs while @code{global_flag} is the case-insensitive 3230name as seen from Fortran. If no binding name is specified, as for 3231@var{tp}, the C binding name is the (lowercase) Fortran binding name. 3232If a binding name is specified, only a single variable may be after the 3233double colon. Note of warning: You cannot use a global variable to 3234access @var{errno} of the C library as the C standard allows it to be 3235a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead. 3236 3237@node Interoperable Subroutines and Functions 3238@subsection Interoperable Subroutines and Functions 3239 3240Subroutines and functions have to have the @code{BIND(C)} attribute to 3241be compatible with C. The dummy argument declaration is relatively 3242straightforward. However, one needs to be careful because C uses 3243call-by-value by default while Fortran behaves usually similar to 3244call-by-reference. Furthermore, strings and pointers are handled 3245differently. Note that in Fortran 2003 and 2008 only explicit size 3246and assumed-size arrays are supported but not assumed-shape or 3247deferred-shape (i.e. allocatable or pointer) arrays. However, those 3248are allowed since the Technical Specification 29113, see 3249@ref{Further Interoperability of Fortran with C} 3250 3251To pass a variable by value, use the @code{VALUE} attribute. 3252Thus, the following C prototype 3253 3254@smallexample 3255@code{int func(int i, int *j)} 3256@end smallexample 3257 3258matches the Fortran declaration 3259 3260@smallexample 3261 integer(c_int) function func(i,j) 3262 use iso_c_binding, only: c_int 3263 integer(c_int), VALUE :: i 3264 integer(c_int) :: j 3265@end smallexample 3266 3267Note that pointer arguments also frequently need the @code{VALUE} attribute, 3268see @ref{Working with Pointers}. 3269 3270Strings are handled quite differently in C and Fortran. In C a string 3271is a @code{NUL}-terminated array of characters while in Fortran each string 3272has a length associated with it and is thus not terminated (by e.g. 3273@code{NUL}). For example, if one wants to use the following C function, 3274 3275@smallexample 3276 #include <stdio.h> 3277 void print_C(char *string) /* equivalent: char string[] */ 3278 @{ 3279 printf("%s\n", string); 3280 @} 3281@end smallexample 3282 3283to print ``Hello World'' from Fortran, one can call it using 3284 3285@smallexample 3286 use iso_c_binding, only: C_CHAR, C_NULL_CHAR 3287 interface 3288 subroutine print_c(string) bind(C, name="print_C") 3289 use iso_c_binding, only: c_char 3290 character(kind=c_char) :: string(*) 3291 end subroutine print_c 3292 end interface 3293 call print_c(C_CHAR_"Hello World"//C_NULL_CHAR) 3294@end smallexample 3295 3296As the example shows, one needs to ensure that the 3297string is @code{NUL} terminated. Additionally, the dummy argument 3298@var{string} of @code{print_C} is a length-one assumed-size 3299array; using @code{character(len=*)} is not allowed. The example 3300above uses @code{c_char_"Hello World"} to ensure the string 3301literal has the right type; typically the default character 3302kind and @code{c_char} are the same and thus @code{"Hello World"} 3303is equivalent. However, the standard does not guarantee this. 3304 3305The use of strings is now further illustrated using the C library 3306function @code{strncpy}, whose prototype is 3307 3308@smallexample 3309 char *strncpy(char *restrict s1, const char *restrict s2, size_t n); 3310@end smallexample 3311 3312The function @code{strncpy} copies at most @var{n} characters from 3313string @var{s2} to @var{s1} and returns @var{s1}. In the following 3314example, we ignore the return value: 3315 3316@smallexample 3317 use iso_c_binding 3318 implicit none 3319 character(len=30) :: str,str2 3320 interface 3321 ! Ignore the return value of strncpy -> subroutine 3322 ! "restrict" is always assumed if we do not pass a pointer 3323 subroutine strncpy(dest, src, n) bind(C) 3324 import 3325 character(kind=c_char), intent(out) :: dest(*) 3326 character(kind=c_char), intent(in) :: src(*) 3327 integer(c_size_t), value, intent(in) :: n 3328 end subroutine strncpy 3329 end interface 3330 str = repeat('X',30) ! Initialize whole string with 'X' 3331 call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, & 3332 len(c_char_"Hello World",kind=c_size_t)) 3333 print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX" 3334 end 3335@end smallexample 3336 3337The intrinsic procedures are described in @ref{Intrinsic Procedures}. 3338 3339@node Working with Pointers 3340@subsection Working with Pointers 3341 3342C pointers are represented in Fortran via the special opaque derived type 3343@code{type(c_ptr)} (with private components). Thus one needs to 3344use intrinsic conversion procedures to convert from or to C pointers. 3345 3346For some applications, using an assumed type (@code{TYPE(*)}) can be an 3347alternative to a C pointer; see 3348@ref{Further Interoperability of Fortran with C}. 3349 3350For example, 3351 3352@smallexample 3353 use iso_c_binding 3354 type(c_ptr) :: cptr1, cptr2 3355 integer, target :: array(7), scalar 3356 integer, pointer :: pa(:), ps 3357 cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the 3358 ! array is contiguous if required by the C 3359 ! procedure 3360 cptr2 = c_loc(scalar) 3361 call c_f_pointer(cptr2, ps) 3362 call c_f_pointer(cptr2, pa, shape=[7]) 3363@end smallexample 3364 3365When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument 3366has to be passed. 3367 3368If a pointer is a dummy-argument of an interoperable procedure, it usually 3369has to be declared using the @code{VALUE} attribute. @code{void*} 3370matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone 3371matches @code{void**}. 3372 3373Procedure pointers are handled analogously to pointers; the C type is 3374@code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are 3375@code{C_F_PROCPOINTER} and @code{C_FUNLOC}. 3376 3377Let us consider two examples of actually passing a procedure pointer from 3378C to Fortran and vice versa. Note that these examples are also very 3379similar to passing ordinary pointers between both languages. First, 3380consider this code in C: 3381 3382@smallexample 3383/* Procedure implemented in Fortran. */ 3384void get_values (void (*)(double)); 3385 3386/* Call-back routine we want called from Fortran. */ 3387void 3388print_it (double x) 3389@{ 3390 printf ("Number is %f.\n", x); 3391@} 3392 3393/* Call Fortran routine and pass call-back to it. */ 3394void 3395foobar () 3396@{ 3397 get_values (&print_it); 3398@} 3399@end smallexample 3400 3401A matching implementation for @code{get_values} in Fortran, that correctly 3402receives the procedure pointer from C and is able to call it, is given 3403in the following @code{MODULE}: 3404 3405@smallexample 3406MODULE m 3407 IMPLICIT NONE 3408 3409 ! Define interface of call-back routine. 3410 ABSTRACT INTERFACE 3411 SUBROUTINE callback (x) 3412 USE, INTRINSIC :: ISO_C_BINDING 3413 REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x 3414 END SUBROUTINE callback 3415 END INTERFACE 3416 3417CONTAINS 3418 3419 ! Define C-bound procedure. 3420 SUBROUTINE get_values (cproc) BIND(C) 3421 USE, INTRINSIC :: ISO_C_BINDING 3422 TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc 3423 3424 PROCEDURE(callback), POINTER :: proc 3425 3426 ! Convert C to Fortran procedure pointer. 3427 CALL C_F_PROCPOINTER (cproc, proc) 3428 3429 ! Call it. 3430 CALL proc (1.0_C_DOUBLE) 3431 CALL proc (-42.0_C_DOUBLE) 3432 CALL proc (18.12_C_DOUBLE) 3433 END SUBROUTINE get_values 3434 3435END MODULE m 3436@end smallexample 3437 3438Next, we want to call a C routine that expects a procedure pointer argument 3439and pass it a Fortran procedure (which clearly must be interoperable!). 3440Again, the C function may be: 3441 3442@smallexample 3443int 3444call_it (int (*func)(int), int arg) 3445@{ 3446 return func (arg); 3447@} 3448@end smallexample 3449 3450It can be used as in the following Fortran code: 3451 3452@smallexample 3453MODULE m 3454 USE, INTRINSIC :: ISO_C_BINDING 3455 IMPLICIT NONE 3456 3457 ! Define interface of C function. 3458 INTERFACE 3459 INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C) 3460 USE, INTRINSIC :: ISO_C_BINDING 3461 TYPE(C_FUNPTR), INTENT(IN), VALUE :: func 3462 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg 3463 END FUNCTION call_it 3464 END INTERFACE 3465 3466CONTAINS 3467 3468 ! Define procedure passed to C function. 3469 ! It must be interoperable! 3470 INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C) 3471 INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg 3472 double_it = arg + arg 3473 END FUNCTION double_it 3474 3475 ! Call C function. 3476 SUBROUTINE foobar () 3477 TYPE(C_FUNPTR) :: cproc 3478 INTEGER(KIND=C_INT) :: i 3479 3480 ! Get C procedure pointer. 3481 cproc = C_FUNLOC (double_it) 3482 3483 ! Use it. 3484 DO i = 1_C_INT, 10_C_INT 3485 PRINT *, call_it (cproc, i) 3486 END DO 3487 END SUBROUTINE foobar 3488 3489END MODULE m 3490@end smallexample 3491 3492@node Further Interoperability of Fortran with C 3493@subsection Further Interoperability of Fortran with C 3494 3495The Technical Specification ISO/IEC TS 29113:2012 on further 3496interoperability of Fortran with C extends the interoperability support 3497of Fortran 2003 and Fortran 2008. Besides removing some restrictions 3498and constraints, it adds assumed-type (@code{TYPE(*)}) and assumed-rank 3499(@code{dimension}) variables and allows for interoperability of 3500assumed-shape, assumed-rank and deferred-shape arrays, including 3501allocatables and pointers. 3502 3503Note: Currently, GNU Fortran does not use internally the array descriptor 3504(dope vector) as specified in the Technical Specification, but uses 3505an array descriptor with different fields. Assumed type and assumed rank 3506formal arguments are converted in the library to the specified form. The 3507ISO_Fortran_binding API functions (also Fortran 2018 18.4) are implemented 3508in libgfortran. Alternatively, the Chasm Language Interoperability Tools, 3509@url{http://chasm-interop.sourceforge.net/}, provide an interface to GNU 3510Fortran's array descriptor. 3511 3512The Technical Specification adds the following new features, which 3513are supported by GNU Fortran: 3514 3515@itemize @bullet 3516 3517@item The @code{ASYNCHRONOUS} attribute has been clarified and 3518extended to allow its use with asynchronous communication in 3519user-provided libraries such as in implementations of the 3520Message Passing Interface specification. 3521 3522@item Many constraints have been relaxed, in particular for 3523the @code{C_LOC} and @code{C_F_POINTER} intrinsics. 3524 3525@item The @code{OPTIONAL} attribute is now allowed for dummy 3526arguments; an absent argument matches a @code{NULL} pointer. 3527 3528@item Assumed types (@code{TYPE(*)}) have been added, which may 3529only be used for dummy arguments. They are unlimited polymorphic 3530but contrary to @code{CLASS(*)} they do not contain any type 3531information, similar to C's @code{void *} pointers. Expressions 3532of any type and kind can be passed; thus, it can be used as 3533replacement for @code{TYPE(C_PTR)}, avoiding the use of 3534@code{C_LOC} in the caller. 3535 3536Note, however, that @code{TYPE(*)} only accepts scalar arguments, 3537unless the @code{DIMENSION} is explicitly specified. As 3538@code{DIMENSION(*)} only supports array (including array elements) but 3539no scalars, it is not a full replacement for @code{C_LOC}. On the 3540other hand, assumed-type assumed-rank dummy arguments 3541(@code{TYPE(*), DIMENSION(..)}) allow for both scalars and arrays, but 3542require special code on the callee side to handle the array descriptor. 3543 3544@item Assumed-rank arrays (@code{DIMENSION(..)}) as dummy argument 3545allow that scalars and arrays of any rank can be passed as actual 3546argument. As the Technical Specification does not provide for direct 3547means to operate with them, they have to be used either from the C side 3548or be converted using @code{C_LOC} and @code{C_F_POINTER} to scalars 3549or arrays of a specific rank. The rank can be determined using the 3550@code{RANK} intrinisic. 3551@end itemize 3552 3553 3554Currently unimplemented: 3555 3556@itemize @bullet 3557 3558@item GNU Fortran always uses an array descriptor, which does not 3559match the one of the Technical Specification. The 3560@code{ISO_Fortran_binding.h} header file and the C functions it 3561specifies are not available. 3562 3563@item Using assumed-shape, assumed-rank and deferred-shape arrays in 3564@code{BIND(C)} procedures is not fully supported. In particular, 3565C interoperable strings of other length than one are not supported 3566as this requires the new array descriptor. 3567@end itemize 3568 3569 3570@node GNU Fortran Compiler Directives 3571@section GNU Fortran Compiler Directives 3572 3573@menu 3574* ATTRIBUTES directive:: 3575* UNROLL directive:: 3576* BUILTIN directive:: 3577* IVDEP directive:: 3578* VECTOR directive:: 3579* NOVECTOR directive:: 3580@end menu 3581 3582@node ATTRIBUTES directive 3583@subsection ATTRIBUTES directive 3584 3585The Fortran standard describes how a conforming program shall 3586behave; however, the exact implementation is not standardized. In order 3587to allow the user to choose specific implementation details, compiler 3588directives can be used to set attributes of variables and procedures 3589which are not part of the standard. Whether a given attribute is 3590supported and its exact effects depend on both the operating system and 3591on the processor; see 3592@ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)} 3593for details. 3594 3595For procedures and procedure pointers, the following attributes can 3596be used to change the calling convention: 3597 3598@itemize 3599@item @code{CDECL} -- standard C calling convention 3600@item @code{STDCALL} -- convention where the called procedure pops the stack 3601@item @code{FASTCALL} -- part of the arguments are passed via registers 3602instead using the stack 3603@end itemize 3604 3605Besides changing the calling convention, the attributes also influence 3606the decoration of the symbol name, e.g., by a leading underscore or by 3607a trailing at-sign followed by the number of bytes on the stack. When 3608assigning a procedure to a procedure pointer, both should use the same 3609calling convention. 3610 3611On some systems, procedures and global variables (module variables and 3612@code{COMMON} blocks) need special handling to be accessible when they 3613are in a shared library. The following attributes are available: 3614 3615@itemize 3616@item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL 3617@item @code{DLLIMPORT} -- reference the function or variable using a 3618global pointer 3619@end itemize 3620 3621For dummy arguments, the @code{NO_ARG_CHECK} attribute can be used; in 3622other compilers, it is also known as @code{IGNORE_TKR}. For dummy arguments 3623with this attribute actual arguments of any type and kind (similar to 3624@code{TYPE(*)}), scalars and arrays of any rank (no equivalent 3625in Fortran standard) are accepted. As with @code{TYPE(*)}, the argument 3626is unlimited polymorphic and no type information is available. 3627Additionally, the argument may only be passed to dummy arguments 3628with the @code{NO_ARG_CHECK} attribute and as argument to the 3629@code{PRESENT} intrinsic function and to @code{C_LOC} of the 3630@code{ISO_C_BINDING} module. 3631 3632Variables with @code{NO_ARG_CHECK} attribute shall be of assumed-type 3633(@code{TYPE(*)}; recommended) or of type @code{INTEGER}, @code{LOGICAL}, 3634@code{REAL} or @code{COMPLEX}. They shall not have the @code{ALLOCATE}, 3635@code{CODIMENSION}, @code{INTENT(OUT)}, @code{POINTER} or @code{VALUE} 3636attribute; furthermore, they shall be either scalar or of assumed-size 3637(@code{dimension(*)}). As @code{TYPE(*)}, the @code{NO_ARG_CHECK} attribute 3638requires an explicit interface. 3639 3640@itemize 3641@item @code{NO_ARG_CHECK} -- disable the type, kind and rank checking 3642@item @code{DEPRECATED} -- print a warning when using a such-tagged 3643deprecated procedure, variable or parameter; the warning can be suppressed 3644with @option{-Wno-deprecated-declarations}. 3645@end itemize 3646 3647 3648The attributes are specified using the syntax 3649 3650@code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list} 3651 3652where in free-form source code only whitespace is allowed before @code{!GCC$} 3653and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall 3654start in the first column. 3655 3656For procedures, the compiler directives shall be placed into the body 3657of the procedure; for variables and procedure pointers, they shall be in 3658the same declaration part as the variable or procedure pointer. 3659 3660 3661@node UNROLL directive 3662@subsection UNROLL directive 3663 3664The syntax of the directive is 3665 3666@code{!GCC$ unroll N} 3667 3668You can use this directive to control how many times a loop should be unrolled. 3669It must be placed immediately before a @code{DO} loop and applies only to the 3670loop that follows. N is an integer constant specifying the unrolling factor. 3671The values of 0 and 1 block any unrolling of the loop. 3672 3673 3674@node BUILTIN directive 3675@subsection BUILTIN directive 3676 3677The syntax of the directive is 3678 3679@code{!GCC$ BUILTIN (B) attributes simd FLAGS IF('target')} 3680 3681You can use this directive to define which middle-end built-ins provide vector 3682implementations. @code{B} is name of the middle-end built-in. @code{FLAGS} 3683are optional and must be either "(inbranch)" or "(notinbranch)". 3684@code{IF} statement is optional and is used to filter multilib ABIs 3685for the built-in that should be vectorized. Example usage: 3686 3687@smallexample 3688!GCC$ builtin (sinf) attributes simd (notinbranch) if('x86_64') 3689@end smallexample 3690 3691The purpose of the directive is to provide an API among the GCC compiler and 3692the GNU C Library which would define vector implementations of math routines. 3693 3694 3695@node IVDEP directive 3696@subsection IVDEP directive 3697 3698The syntax of the directive is 3699 3700@code{!GCC$ ivdep} 3701 3702This directive tells the compiler to ignore vector dependencies in the 3703following loop. It must be placed immediately before a @code{DO} loop 3704and applies only to the loop that follows. 3705 3706Sometimes the compiler may not have sufficient information to decide 3707whether a particular loop is vectorizable due to potential 3708dependencies between iterations. The purpose of the directive is to 3709tell the compiler that vectorization is safe. 3710 3711This directive is intended for annotation of existing code. For new 3712code it is recommended to consider OpenMP SIMD directives as potential 3713alternative. 3714 3715 3716@node VECTOR directive 3717@subsection VECTOR directive 3718 3719The syntax of the directive is 3720 3721@code{!GCC$ vector} 3722 3723This directive tells the compiler to vectorize the following loop. It 3724must be placed immediately before a @code{DO} loop and applies only to 3725the loop that follows. 3726 3727 3728@node NOVECTOR directive 3729@subsection NOVECTOR directive 3730 3731The syntax of the directive is 3732 3733@code{!GCC$ novector} 3734 3735This directive tells the compiler to not vectorize the following loop. 3736It must be placed immediately before a @code{DO} loop and applies only 3737to the loop that follows. 3738 3739 3740@node Non-Fortran Main Program 3741@section Non-Fortran Main Program 3742 3743@menu 3744* _gfortran_set_args:: Save command-line arguments 3745* _gfortran_set_options:: Set library option flags 3746* _gfortran_set_convert:: Set endian conversion 3747* _gfortran_set_record_marker:: Set length of record markers 3748* _gfortran_set_fpe:: Set when a Floating Point Exception should be raised 3749* _gfortran_set_max_subrecord_length:: Set subrecord length 3750@end menu 3751 3752Even if you are doing mixed-language programming, it is very 3753likely that you do not need to know or use the information in this 3754section. Since it is about the internal structure of GNU Fortran, 3755it may also change in GCC minor releases. 3756 3757When you compile a @code{PROGRAM} with GNU Fortran, a function 3758with the name @code{main} (in the symbol table of the object file) 3759is generated, which initializes the libgfortran library and then 3760calls the actual program which uses the name @code{MAIN__}, for 3761historic reasons. If you link GNU Fortran compiled procedures 3762to, e.g., a C or C++ program or to a Fortran program compiled by 3763a different compiler, the libgfortran library is not initialized 3764and thus a few intrinsic procedures do not work properly, e.g. 3765those for obtaining the command-line arguments. 3766 3767Therefore, if your @code{PROGRAM} is not compiled with 3768GNU Fortran and the GNU Fortran compiled procedures require 3769intrinsics relying on the library initialization, you need to 3770initialize the library yourself. Using the default options, 3771gfortran calls @code{_gfortran_set_args} and 3772@code{_gfortran_set_options}. The initialization of the former 3773is needed if the called procedures access the command line 3774(and for backtracing); the latter sets some flags based on the 3775standard chosen or to enable backtracing. In typical programs, 3776it is not necessary to call any initialization function. 3777 3778If your @code{PROGRAM} is compiled with GNU Fortran, you shall 3779not call any of the following functions. The libgfortran 3780initialization functions are shown in C syntax but using C 3781bindings they are also accessible from Fortran. 3782 3783 3784@node _gfortran_set_args 3785@subsection @code{_gfortran_set_args} --- Save command-line arguments 3786@fnindex _gfortran_set_args 3787@cindex libgfortran initialization, set_args 3788 3789@table @asis 3790@item @emph{Description}: 3791@code{_gfortran_set_args} saves the command-line arguments; this 3792initialization is required if any of the command-line intrinsics 3793is called. Additionally, it shall be called if backtracing is 3794enabled (see @code{_gfortran_set_options}). 3795 3796@item @emph{Syntax}: 3797@code{void _gfortran_set_args (int argc, char *argv[])} 3798 3799@item @emph{Arguments}: 3800@multitable @columnfractions .15 .70 3801@item @var{argc} @tab number of command line argument strings 3802@item @var{argv} @tab the command-line argument strings; argv[0] 3803is the pathname of the executable itself. 3804@end multitable 3805 3806@item @emph{Example}: 3807@smallexample 3808int main (int argc, char *argv[]) 3809@{ 3810 /* Initialize libgfortran. */ 3811 _gfortran_set_args (argc, argv); 3812 return 0; 3813@} 3814@end smallexample 3815@end table 3816 3817 3818@node _gfortran_set_options 3819@subsection @code{_gfortran_set_options} --- Set library option flags 3820@fnindex _gfortran_set_options 3821@cindex libgfortran initialization, set_options 3822 3823@table @asis 3824@item @emph{Description}: 3825@code{_gfortran_set_options} sets several flags related to the Fortran 3826standard to be used, whether backtracing should be enabled 3827and whether range checks should be performed. The syntax allows for 3828upward compatibility since the number of passed flags is specified; for 3829non-passed flags, the default value is used. See also 3830@pxref{Code Gen Options}. Please note that not all flags are actually 3831used. 3832 3833@item @emph{Syntax}: 3834@code{void _gfortran_set_options (int num, int options[])} 3835 3836@item @emph{Arguments}: 3837@multitable @columnfractions .15 .70 3838@item @var{num} @tab number of options passed 3839@item @var{argv} @tab The list of flag values 3840@end multitable 3841 3842@item @emph{option flag list}: 3843@multitable @columnfractions .15 .70 3844@item @var{option}[0] @tab Allowed standard; can give run-time errors 3845if e.g. an input-output edit descriptor is invalid in a given 3846standard. Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1), 3847@code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4), 3848@code{GFC_STD_F95} (8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU} 3849(32), @code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128), 3850@code{GFC_STD_F2008_OBS} (256), @code{GFC_STD_F2008_TS} (512), 3851@code{GFC_STD_F2018} (1024), @code{GFC_STD_F2018_OBS} (2048), and 3852@code{GFC_STD=F2018_DEL} (4096). Default: @code{GFC_STD_F95_OBS | 3853GFC_STD_F95_DEL | GFC_STD_F95 | GFC_STD_F2003 | GFC_STD_F2008 | 3854GFC_STD_F2008_TS | GFC_STD_F2008_OBS | GFC_STD_F77 | GFC_STD_F2018 | 3855GFC_STD_F2018_OBS | GFC_STD_F2018_DEL | GFC_STD_GNU | GFC_STD_LEGACY}. 3856@item @var{option}[1] @tab Standard-warning flag; prints a warning to 3857standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}. 3858@item @var{option}[2] @tab If non zero, enable pedantic checking. 3859Default: off. 3860@item @var{option}[3] @tab Unused. 3861@item @var{option}[4] @tab If non zero, enable backtracing on run-time 3862errors. Default: off. (Default in the compiler: on.) 3863Note: Installs a signal handler and requires command-line 3864initialization using @code{_gfortran_set_args}. 3865@item @var{option}[5] @tab If non zero, supports signed zeros. 3866Default: enabled. 3867@item @var{option}[6] @tab Enables run-time checking. Possible values 3868are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2), 3869GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (8), GFC_RTCHECK_POINTER (16), 3870GFC_RTCHECK_MEM (32), GFC_RTCHECK_BITS (64). 3871Default: disabled. 3872@item @var{option}[7] @tab Unused. 3873@item @var{option}[8] @tab Show a warning when invoking @code{STOP} and 3874@code{ERROR STOP} if a floating-point exception occurred. Possible values 3875are (bitwise or-ed) @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2), 3876@code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8), 3877@code{GFC_FPE_UNDERFLOW} (16), @code{GFC_FPE_INEXACT} (32). Default: None (0). 3878(Default in the compiler: @code{GFC_FPE_INVALID | GFC_FPE_DENORMAL | 3879GFC_FPE_ZERO | GFC_FPE_OVERFLOW | GFC_FPE_UNDERFLOW}.) 3880@end multitable 3881 3882@item @emph{Example}: 3883@smallexample 3884 /* Use gfortran 4.9 default options. */ 3885 static int options[] = @{68, 511, 0, 0, 1, 1, 0, 0, 31@}; 3886 _gfortran_set_options (9, &options); 3887@end smallexample 3888@end table 3889 3890 3891@node _gfortran_set_convert 3892@subsection @code{_gfortran_set_convert} --- Set endian conversion 3893@fnindex _gfortran_set_convert 3894@cindex libgfortran initialization, set_convert 3895 3896@table @asis 3897@item @emph{Description}: 3898@code{_gfortran_set_convert} set the representation of data for 3899unformatted files. 3900 3901@item @emph{Syntax}: 3902@code{void _gfortran_set_convert (int conv)} 3903 3904@item @emph{Arguments}: 3905@multitable @columnfractions .15 .70 3906@item @var{conv} @tab Endian conversion, possible values: 3907GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1), 3908GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3). 3909@end multitable 3910 3911@item @emph{Example}: 3912@smallexample 3913int main (int argc, char *argv[]) 3914@{ 3915 /* Initialize libgfortran. */ 3916 _gfortran_set_args (argc, argv); 3917 _gfortran_set_convert (1); 3918 return 0; 3919@} 3920@end smallexample 3921@end table 3922 3923 3924@node _gfortran_set_record_marker 3925@subsection @code{_gfortran_set_record_marker} --- Set length of record markers 3926@fnindex _gfortran_set_record_marker 3927@cindex libgfortran initialization, set_record_marker 3928 3929@table @asis 3930@item @emph{Description}: 3931@code{_gfortran_set_record_marker} sets the length of record markers 3932for unformatted files. 3933 3934@item @emph{Syntax}: 3935@code{void _gfortran_set_record_marker (int val)} 3936 3937@item @emph{Arguments}: 3938@multitable @columnfractions .15 .70 3939@item @var{val} @tab Length of the record marker; valid values 3940are 4 and 8. Default is 4. 3941@end multitable 3942 3943@item @emph{Example}: 3944@smallexample 3945int main (int argc, char *argv[]) 3946@{ 3947 /* Initialize libgfortran. */ 3948 _gfortran_set_args (argc, argv); 3949 _gfortran_set_record_marker (8); 3950 return 0; 3951@} 3952@end smallexample 3953@end table 3954 3955 3956@node _gfortran_set_fpe 3957@subsection @code{_gfortran_set_fpe} --- Enable floating point exception traps 3958@fnindex _gfortran_set_fpe 3959@cindex libgfortran initialization, set_fpe 3960 3961@table @asis 3962@item @emph{Description}: 3963@code{_gfortran_set_fpe} enables floating point exception traps for 3964the specified exceptions. On most systems, this will result in a 3965SIGFPE signal being sent and the program being aborted. 3966 3967@item @emph{Syntax}: 3968@code{void _gfortran_set_fpe (int val)} 3969 3970@item @emph{Arguments}: 3971@multitable @columnfractions .15 .70 3972@item @var{option}[0] @tab IEEE exceptions. Possible values are 3973(bitwise or-ed) zero (0, default) no trapping, 3974@code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2), 3975@code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8), 3976@code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_INEXACT} (32). 3977@end multitable 3978 3979@item @emph{Example}: 3980@smallexample 3981int main (int argc, char *argv[]) 3982@{ 3983 /* Initialize libgfortran. */ 3984 _gfortran_set_args (argc, argv); 3985 /* FPE for invalid operations such as SQRT(-1.0). */ 3986 _gfortran_set_fpe (1); 3987 return 0; 3988@} 3989@end smallexample 3990@end table 3991 3992 3993@node _gfortran_set_max_subrecord_length 3994@subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length 3995@fnindex _gfortran_set_max_subrecord_length 3996@cindex libgfortran initialization, set_max_subrecord_length 3997 3998@table @asis 3999@item @emph{Description}: 4000@code{_gfortran_set_max_subrecord_length} set the maximum length 4001for a subrecord. This option only makes sense for testing and 4002debugging of unformatted I/O. 4003 4004@item @emph{Syntax}: 4005@code{void _gfortran_set_max_subrecord_length (int val)} 4006 4007@item @emph{Arguments}: 4008@multitable @columnfractions .15 .70 4009@item @var{val} @tab the maximum length for a subrecord; 4010the maximum permitted value is 2147483639, which is also 4011the default. 4012@end multitable 4013 4014@item @emph{Example}: 4015@smallexample 4016int main (int argc, char *argv[]) 4017@{ 4018 /* Initialize libgfortran. */ 4019 _gfortran_set_args (argc, argv); 4020 _gfortran_set_max_subrecord_length (8); 4021 return 0; 4022@} 4023@end smallexample 4024@end table 4025 4026 4027@node Naming and argument-passing conventions 4028@section Naming and argument-passing conventions 4029 4030This section gives an overview about the naming convention of procedures 4031and global variables and about the argument passing conventions used by 4032GNU Fortran. If a C binding has been specified, the naming convention 4033and some of the argument-passing conventions change. If possible, 4034mixed-language and mixed-compiler projects should use the better defined 4035C binding for interoperability. See @pxref{Interoperability with C}. 4036 4037@menu 4038* Naming conventions:: 4039* Argument passing conventions:: 4040@end menu 4041 4042 4043@node Naming conventions 4044@subsection Naming conventions 4045 4046According the Fortran standard, valid Fortran names consist of a letter 4047between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0}, 4048@code{1} to @code{9} and underscores (@code{_}) with the restriction 4049that names may only start with a letter. As vendor extension, the 4050dollar sign (@code{$}) is additionally permitted with the option 4051@option{-fdollar-ok}, but not as first character and only if the 4052target system supports it. 4053 4054By default, the procedure name is the lower-cased Fortran name with an 4055appended underscore (@code{_}); using @option{-fno-underscoring} no 4056underscore is appended while @code{-fsecond-underscore} appends two 4057underscores. Depending on the target system and the calling convention, 4058the procedure might be additionally dressed; for instance, on 32bit 4059Windows with @code{stdcall}, an at-sign @code{@@} followed by an integer 4060number is appended. For the changing the calling convention, see 4061@pxref{GNU Fortran Compiler Directives}. 4062 4063For common blocks, the same convention is used, i.e. by default an 4064underscore is appended to the lower-cased Fortran name. Blank commons 4065have the name @code{__BLNK__}. 4066 4067For procedures and variables declared in the specification space of a 4068module, the name is formed by @code{__}, followed by the lower-cased 4069module name, @code{_MOD_}, and the lower-cased Fortran name. Note that 4070no underscore is appended. 4071 4072 4073@node Argument passing conventions 4074@subsection Argument passing conventions 4075 4076Subroutines do not return a value (matching C99's @code{void}) while 4077functions either return a value as specified in the platform ABI or 4078the result variable is passed as hidden argument to the function and 4079no result is returned. A hidden result variable is used when the 4080result variable is an array or of type @code{CHARACTER}. 4081 4082Arguments are passed according to the platform ABI. In particular, 4083complex arguments might not be compatible to a struct with two real 4084components for the real and imaginary part. The argument passing 4085matches the one of C99's @code{_Complex}. Functions with scalar 4086complex result variables return their value and do not use a 4087by-reference argument. Note that with the @option{-ff2c} option, 4088the argument passing is modified and no longer completely matches 4089the platform ABI. Some other Fortran compilers use @code{f2c} 4090semantic by default; this might cause problems with 4091interoperablility. 4092 4093GNU Fortran passes most arguments by reference, i.e. by passing a 4094pointer to the data. Note that the compiler might use a temporary 4095variable into which the actual argument has been copied, if required 4096semantically (copy-in/copy-out). 4097 4098For arguments with @code{ALLOCATABLE} and @code{POINTER} 4099attribute (including procedure pointers), a pointer to the pointer 4100is passed such that the pointer address can be modified in the 4101procedure. 4102 4103For dummy arguments with the @code{VALUE} attribute: Scalar arguments 4104of the type @code{INTEGER}, @code{LOGICAL}, @code{REAL} and 4105@code{COMPLEX} are passed by value according to the platform ABI. 4106(As vendor extension and not recommended, using @code{%VAL()} in the 4107call to a procedure has the same effect.) For @code{TYPE(C_PTR)} and 4108procedure pointers, the pointer itself is passed such that it can be 4109modified without affecting the caller. 4110@c FIXME: Document how VALUE is handled for CHARACTER, TYPE, 4111@c CLASS and arrays, i.e. whether the copy-in is done in the caller 4112@c or in the callee. 4113 4114For Boolean (@code{LOGICAL}) arguments, please note that GCC expects 4115only the integer value 0 and 1. If a GNU Fortran @code{LOGICAL} 4116variable contains another integer value, the result is undefined. 4117As some other Fortran compilers use @math{-1} for @code{.TRUE.}, 4118extra care has to be taken -- such as passing the value as 4119@code{INTEGER}. (The same value restriction also applies to other 4120front ends of GCC, e.g. to GCC's C99 compiler for @code{_Bool} 4121or GCC's Ada compiler for @code{Boolean}.) 4122 4123For arguments of @code{CHARACTER} type, the character length is passed 4124as a hidden argument at the end of the argument list. For 4125deferred-length strings, the value is passed by reference, otherwise 4126by value. The character length has the C type @code{size_t} (or 4127@code{INTEGER(kind=C_SIZE_T)} in Fortran). Note that this is 4128different to older versions of the GNU Fortran compiler, where the 4129type of the hidden character length argument was a C @code{int}. In 4130order to retain compatibility with older versions, one can e.g. for 4131the following Fortran procedure 4132 4133@smallexample 4134subroutine fstrlen (s, a) 4135 character(len=*) :: s 4136 integer :: a 4137 print*, len(s) 4138end subroutine fstrlen 4139@end smallexample 4140 4141define the corresponding C prototype as follows: 4142 4143@smallexample 4144#if __GNUC__ > 7 4145typedef size_t fortran_charlen_t; 4146#else 4147typedef int fortran_charlen_t; 4148#endif 4149 4150void fstrlen_ (char*, int*, fortran_charlen_t); 4151@end smallexample 4152 4153In order to avoid such compiler-specific details, for new code it is 4154instead recommended to use the ISO_C_BINDING feature. 4155 4156Note with C binding, @code{CHARACTER(len=1)} result variables are 4157returned according to the platform ABI and no hidden length argument 4158is used for dummy arguments; with @code{VALUE}, those variables are 4159passed by value. 4160 4161For @code{OPTIONAL} dummy arguments, an absent argument is denoted 4162by a NULL pointer, except for scalar dummy arguments of type 4163@code{INTEGER}, @code{LOGICAL}, @code{REAL} and @code{COMPLEX} 4164which have the @code{VALUE} attribute. For those, a hidden Boolean 4165argument (@code{logical(kind=C_bool),value}) is used to indicate 4166whether the argument is present. 4167 4168Arguments which are assumed-shape, assumed-rank or deferred-rank 4169arrays or, with @option{-fcoarray=lib}, allocatable scalar coarrays use 4170an array descriptor. All other arrays pass the address of the 4171first element of the array. With @option{-fcoarray=lib}, the token 4172and the offset belonging to nonallocatable coarrays dummy arguments 4173are passed as hidden argument along the character length hidden 4174arguments. The token is an opaque pointer identifying the coarray 4175and the offset is a passed-by-value integer of kind @code{C_PTRDIFF_T}, 4176denoting the byte offset between the base address of the coarray and 4177the passed scalar or first element of the passed array. 4178 4179The arguments are passed in the following order 4180@itemize @bullet 4181@item Result variable, when the function result is passed by reference 4182@item Character length of the function result, if it is a of type 4183@code{CHARACTER} and no C binding is used 4184@item The arguments in the order in which they appear in the Fortran 4185declaration 4186@item The the present status for optional arguments with value attribute, 4187which are internally passed by value 4188@item The character length and/or coarray token and offset for the first 4189argument which is a @code{CHARACTER} or a nonallocatable coarray dummy 4190argument, followed by the hidden arguments of the next dummy argument 4191of such a type 4192@end itemize 4193 4194 4195@c --------------------------------------------------------------------- 4196@c Coarray Programming 4197@c --------------------------------------------------------------------- 4198 4199@node Coarray Programming 4200@chapter Coarray Programming 4201@cindex Coarrays 4202 4203@menu 4204* Type and enum ABI Documentation:: 4205* Function ABI Documentation:: 4206@end menu 4207 4208 4209@node Type and enum ABI Documentation 4210@section Type and enum ABI Documentation 4211 4212@menu 4213* caf_token_t:: 4214* caf_register_t:: 4215* caf_deregister_t:: 4216* caf_reference_t:: 4217* caf_team_t:: 4218@end menu 4219 4220@node caf_token_t 4221@subsection @code{caf_token_t} 4222 4223Typedef of type @code{void *} on the compiler side. Can be any data 4224type on the library side. 4225 4226@node caf_register_t 4227@subsection @code{caf_register_t} 4228 4229Indicates which kind of coarray variable should be registered. 4230 4231@verbatim 4232typedef enum caf_register_t { 4233 CAF_REGTYPE_COARRAY_STATIC, 4234 CAF_REGTYPE_COARRAY_ALLOC, 4235 CAF_REGTYPE_LOCK_STATIC, 4236 CAF_REGTYPE_LOCK_ALLOC, 4237 CAF_REGTYPE_CRITICAL, 4238 CAF_REGTYPE_EVENT_STATIC, 4239 CAF_REGTYPE_EVENT_ALLOC, 4240 CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY, 4241 CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY 4242} 4243caf_register_t; 4244@end verbatim 4245 4246The values @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and 4247@code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} are for allocatable components 4248in derived type coarrays only. The first one sets up the token without 4249allocating memory for allocatable component. The latter one only allocates the 4250memory for an allocatable component in a derived type coarray. The token 4251needs to be setup previously by the REGISTER_ONLY. This allows to have 4252allocatable components un-allocated on some images. The status whether an 4253allocatable component is allocated on a remote image can be queried by 4254@code{_caf_is_present} which used internally by the @code{ALLOCATED} 4255intrinsic. 4256 4257@node caf_deregister_t 4258@subsection @code{caf_deregister_t} 4259 4260@verbatim 4261typedef enum caf_deregister_t { 4262 CAF_DEREGTYPE_COARRAY_DEREGISTER, 4263 CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY 4264} 4265caf_deregister_t; 4266@end verbatim 4267 4268Allows to specifiy the type of deregistration of a coarray object. The 4269@code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} flag is only allowed for 4270allocatable components in derived type coarrays. 4271 4272@node caf_reference_t 4273@subsection @code{caf_reference_t} 4274 4275The structure used for implementing arbitrary reference chains. 4276A @code{CAF_REFERENCE_T} allows to specify a component reference or any kind 4277of array reference of any rank supported by gfortran. For array references all 4278kinds as known by the compiler/Fortran standard are supported indicated by 4279a @code{MODE}. 4280 4281@verbatim 4282typedef enum caf_ref_type_t { 4283 /* Reference a component of a derived type, either regular one or an 4284 allocatable or pointer type. For regular ones idx in caf_reference_t is 4285 set to -1. */ 4286 CAF_REF_COMPONENT, 4287 /* Reference an allocatable array. */ 4288 CAF_REF_ARRAY, 4289 /* Reference a non-allocatable/non-pointer array. I.e., the coarray object 4290 has no array descriptor associated and the addressing is done 4291 completely using the ref. */ 4292 CAF_REF_STATIC_ARRAY 4293} caf_ref_type_t; 4294@end verbatim 4295 4296@verbatim 4297typedef enum caf_array_ref_t { 4298 /* No array ref. This terminates the array ref. */ 4299 CAF_ARR_REF_NONE = 0, 4300 /* Reference array elements given by a vector. Only for this mode 4301 caf_reference_t.u.a.dim[i].v is valid. */ 4302 CAF_ARR_REF_VECTOR, 4303 /* A full array ref (:). */ 4304 CAF_ARR_REF_FULL, 4305 /* Reference a range on elements given by start, end and stride. */ 4306 CAF_ARR_REF_RANGE, 4307 /* Only a single item is referenced given in the start member. */ 4308 CAF_ARR_REF_SINGLE, 4309 /* An array ref of the kind (i:), where i is an arbitrary valid index in the 4310 array. The index i is given in the start member. */ 4311 CAF_ARR_REF_OPEN_END, 4312 /* An array ref of the kind (:i), where the lower bound of the array ref 4313 is given by the remote side. The index i is given in the end member. */ 4314 CAF_ARR_REF_OPEN_START 4315} caf_array_ref_t; 4316@end verbatim 4317 4318@verbatim 4319/* References to remote components of a derived type. */ 4320typedef struct caf_reference_t { 4321 /* A pointer to the next ref or NULL. */ 4322 struct caf_reference_t *next; 4323 /* The type of the reference. */ 4324 /* caf_ref_type_t, replaced by int to allow specification in fortran FE. */ 4325 int type; 4326 /* The size of an item referenced in bytes. I.e. in an array ref this is 4327 the factor to advance the array pointer with to get to the next item. 4328 For component refs this gives just the size of the element referenced. */ 4329 size_t item_size; 4330 union { 4331 struct { 4332 /* The offset (in bytes) of the component in the derived type. 4333 Unused for allocatable or pointer components. */ 4334 ptrdiff_t offset; 4335 /* The offset (in bytes) to the caf_token associated with this 4336 component. NULL, when not allocatable/pointer ref. */ 4337 ptrdiff_t caf_token_offset; 4338 } c; 4339 struct { 4340 /* The mode of the array ref. See CAF_ARR_REF_*. */ 4341 /* caf_array_ref_t, replaced by unsigend char to allow specification in 4342 fortran FE. */ 4343 unsigned char mode[GFC_MAX_DIMENSIONS]; 4344 /* The type of a static array. Unset for array's with descriptors. */ 4345 int static_array_type; 4346 /* Subscript refs (s) or vector refs (v). */ 4347 union { 4348 struct { 4349 /* The start and end boundary of the ref and the stride. */ 4350 index_type start, end, stride; 4351 } s; 4352 struct { 4353 /* nvec entries of kind giving the elements to reference. */ 4354 void *vector; 4355 /* The number of entries in vector. */ 4356 size_t nvec; 4357 /* The integer kind used for the elements in vector. */ 4358 int kind; 4359 } v; 4360 } dim[GFC_MAX_DIMENSIONS]; 4361 } a; 4362 } u; 4363} caf_reference_t; 4364@end verbatim 4365 4366The references make up a single linked list of reference operations. The 4367@code{NEXT} member links to the next reference or NULL to indicate the end of 4368the chain. Component and array refs can be arbitrarily mixed as long as they 4369comply to the Fortran standard. 4370 4371@emph{NOTES} 4372The member @code{STATIC_ARRAY_TYPE} is used only when the @code{TYPE} is 4373@code{CAF_REF_STATIC_ARRAY}. The member gives the type of the data referenced. 4374Because no array descriptor is available for a descriptor-less array and 4375type conversion still needs to take place the type is transported here. 4376 4377At the moment @code{CAF_ARR_REF_VECTOR} is not implemented in the front end for 4378descriptor-less arrays. The library caf_single has untested support for it. 4379 4380@node caf_team_t 4381@subsection @code{caf_team_t} 4382 4383Opaque pointer to represent a team-handle. This type is a stand-in for the 4384future implementation of teams. It is about to change without further notice. 4385 4386@node Function ABI Documentation 4387@section Function ABI Documentation 4388 4389@menu 4390* _gfortran_caf_init:: Initialiation function 4391* _gfortran_caf_finish:: Finalization function 4392* _gfortran_caf_this_image:: Querying the image number 4393* _gfortran_caf_num_images:: Querying the maximal number of images 4394* _gfortran_caf_image_status :: Query the status of an image 4395* _gfortran_caf_failed_images :: Get an array of the indexes of the failed images 4396* _gfortran_caf_stopped_images :: Get an array of the indexes of the stopped images 4397* _gfortran_caf_register:: Registering coarrays 4398* _gfortran_caf_deregister:: Deregistering coarrays 4399* _gfortran_caf_is_present:: Query whether an allocatable or pointer component in a derived type coarray is allocated 4400* _gfortran_caf_send:: Sending data from a local image to a remote image 4401* _gfortran_caf_get:: Getting data from a remote image 4402* _gfortran_caf_sendget:: Sending data between remote images 4403* _gfortran_caf_send_by_ref:: Sending data from a local image to a remote image using enhanced references 4404* _gfortran_caf_get_by_ref:: Getting data from a remote image using enhanced references 4405* _gfortran_caf_sendget_by_ref:: Sending data between remote images using enhanced references 4406* _gfortran_caf_lock:: Locking a lock variable 4407* _gfortran_caf_unlock:: Unlocking a lock variable 4408* _gfortran_caf_event_post:: Post an event 4409* _gfortran_caf_event_wait:: Wait that an event occurred 4410* _gfortran_caf_event_query:: Query event count 4411* _gfortran_caf_sync_all:: All-image barrier 4412* _gfortran_caf_sync_images:: Barrier for selected images 4413* _gfortran_caf_sync_memory:: Wait for completion of segment-memory operations 4414* _gfortran_caf_error_stop:: Error termination with exit code 4415* _gfortran_caf_error_stop_str:: Error termination with string 4416* _gfortran_caf_fail_image :: Mark the image failed and end its execution 4417* _gfortran_caf_atomic_define:: Atomic variable assignment 4418* _gfortran_caf_atomic_ref:: Atomic variable reference 4419* _gfortran_caf_atomic_cas:: Atomic compare and swap 4420* _gfortran_caf_atomic_op:: Atomic operation 4421* _gfortran_caf_co_broadcast:: Sending data to all images 4422* _gfortran_caf_co_max:: Collective maximum reduction 4423* _gfortran_caf_co_min:: Collective minimum reduction 4424* _gfortran_caf_co_sum:: Collective summing reduction 4425* _gfortran_caf_co_reduce:: Generic collective reduction 4426@end menu 4427 4428 4429@node _gfortran_caf_init 4430@subsection @code{_gfortran_caf_init} --- Initialiation function 4431@cindex Coarray, _gfortran_caf_init 4432 4433@table @asis 4434@item @emph{Description}: 4435This function is called at startup of the program before the Fortran main 4436program, if the latter has been compiled with @option{-fcoarray=lib}. 4437It takes as arguments the command-line arguments of the program. It is 4438permitted to pass two @code{NULL} pointers as argument; if non-@code{NULL}, 4439the library is permitted to modify the arguments. 4440 4441@item @emph{Syntax}: 4442@code{void _gfortran_caf_init (int *argc, char ***argv)} 4443 4444@item @emph{Arguments}: 4445@multitable @columnfractions .15 .70 4446@item @var{argc} @tab intent(inout) An integer pointer with the number of 4447arguments passed to the program or @code{NULL}. 4448@item @var{argv} @tab intent(inout) A pointer to an array of strings with the 4449command-line arguments or @code{NULL}. 4450@end multitable 4451 4452@item @emph{NOTES} 4453The function is modelled after the initialization function of the Message 4454Passing Interface (MPI) specification. Due to the way coarray registration 4455works, it might not be the first call to the library. If the main program is 4456not written in Fortran and only a library uses coarrays, it can happen that 4457this function is never called. Therefore, it is recommended that the library 4458does not rely on the passed arguments and whether the call has been done. 4459@end table 4460 4461 4462@node _gfortran_caf_finish 4463@subsection @code{_gfortran_caf_finish} --- Finalization function 4464@cindex Coarray, _gfortran_caf_finish 4465 4466@table @asis 4467@item @emph{Description}: 4468This function is called at the end of the Fortran main program, if it has 4469been compiled with the @option{-fcoarray=lib} option. 4470 4471@item @emph{Syntax}: 4472@code{void _gfortran_caf_finish (void)} 4473 4474@item @emph{NOTES} 4475For non-Fortran programs, it is recommended to call the function at the end 4476of the main program. To ensure that the shutdown is also performed for 4477programs where this function is not explicitly invoked, for instance 4478non-Fortran programs or calls to the system's exit() function, the library 4479can use a destructor function. Note that programs can also be terminated 4480using the STOP and ERROR STOP statements; those use different library calls. 4481@end table 4482 4483 4484@node _gfortran_caf_this_image 4485@subsection @code{_gfortran_caf_this_image} --- Querying the image number 4486@cindex Coarray, _gfortran_caf_this_image 4487 4488@table @asis 4489@item @emph{Description}: 4490This function returns the current image number, which is a positive number. 4491 4492@item @emph{Syntax}: 4493@code{int _gfortran_caf_this_image (int distance)} 4494 4495@item @emph{Arguments}: 4496@multitable @columnfractions .15 .70 4497@item @var{distance} @tab As specified for the @code{this_image} intrinsic 4498in TS18508. Shall be a non-negative number. 4499@end multitable 4500 4501@item @emph{NOTES} 4502If the Fortran intrinsic @code{this_image} is invoked without an argument, which 4503is the only permitted form in Fortran 2008, GCC passes @code{0} as 4504first argument. 4505@end table 4506 4507 4508@node _gfortran_caf_num_images 4509@subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images 4510@cindex Coarray, _gfortran_caf_num_images 4511 4512@table @asis 4513@item @emph{Description}: 4514This function returns the number of images in the current team, if 4515@var{distance} is 0 or the number of images in the parent team at the specified 4516distance. If failed is -1, the function returns the number of all images at 4517the specified distance; if it is 0, the function returns the number of 4518nonfailed images, and if it is 1, it returns the number of failed images. 4519 4520@item @emph{Syntax}: 4521@code{int _gfortran_caf_num_images(int distance, int failed)} 4522 4523@item @emph{Arguments}: 4524@multitable @columnfractions .15 .70 4525@item @var{distance} @tab the distance from this image to the ancestor. 4526Shall be positive. 4527@item @var{failed} @tab shall be -1, 0, or 1 4528@end multitable 4529 4530@item @emph{NOTES} 4531This function follows TS18508. If the num_image intrinsic has no arguments, 4532then the compiler passes @code{distance=0} and @code{failed=-1} to the function. 4533@end table 4534 4535 4536@node _gfortran_caf_image_status 4537@subsection @code{_gfortran_caf_image_status} --- Query the status of an image 4538@cindex Coarray, _gfortran_caf_image_status 4539 4540@table @asis 4541@item @emph{Description}: 4542Get the status of the image given by the id @var{image} of the team given by 4543@var{team}. Valid results are zero, for image is ok, @code{STAT_STOPPED_IMAGE} 4544from the ISO_FORTRAN_ENV module to indicate that the image has been stopped and 4545@code{STAT_FAILED_IMAGE} also from ISO_FORTRAN_ENV to indicate that the image 4546has executed a @code{FAIL IMAGE} statement. 4547 4548@item @emph{Syntax}: 4549@code{int _gfortran_caf_image_status (int image, caf_team_t * team)} 4550 4551@item @emph{Arguments}: 4552@multitable @columnfractions .15 .70 4553@item @var{image} @tab the positive scalar id of the image in the current TEAM. 4554@item @var{team} @tab optional; team on the which the inquiry is to be 4555performed. 4556@end multitable 4557 4558@item @emph{NOTES} 4559This function follows TS18508. Because team-functionality is not yet 4560implemented a null-pointer is passed for the @var{team} argument at the moment. 4561@end table 4562 4563 4564@node _gfortran_caf_failed_images 4565@subsection @code{_gfortran_caf_failed_images} --- Get an array of the indexes of the failed images 4566@cindex Coarray, _gfortran_caf_failed_images 4567 4568@table @asis 4569@item @emph{Description}: 4570Get an array of image indexes in the current @var{team} that have failed. The 4571array is sorted ascendingly. When @var{team} is not provided the current team 4572is to be used. When @var{kind} is provided then the resulting array is of that 4573integer kind else it is of default integer kind. The returns an unallocated 4574size zero array when no images have failed. 4575 4576@item @emph{Syntax}: 4577@code{int _gfortran_caf_failed_images (caf_team_t * team, int * kind)} 4578 4579@item @emph{Arguments}: 4580@multitable @columnfractions .15 .70 4581@item @var{team} @tab optional; team on the which the inquiry is to be 4582performed. 4583@item @var{image} @tab optional; the kind of the resulting integer array. 4584@end multitable 4585 4586@item @emph{NOTES} 4587This function follows TS18508. Because team-functionality is not yet 4588implemented a null-pointer is passed for the @var{team} argument at the moment. 4589@end table 4590 4591 4592@node _gfortran_caf_stopped_images 4593@subsection @code{_gfortran_caf_stopped_images} --- Get an array of the indexes of the stopped images 4594@cindex Coarray, _gfortran_caf_stopped_images 4595 4596@table @asis 4597@item @emph{Description}: 4598Get an array of image indexes in the current @var{team} that have stopped. The 4599array is sorted ascendingly. When @var{team} is not provided the current team 4600is to be used. When @var{kind} is provided then the resulting array is of that 4601integer kind else it is of default integer kind. The returns an unallocated 4602size zero array when no images have failed. 4603 4604@item @emph{Syntax}: 4605@code{int _gfortran_caf_stopped_images (caf_team_t * team, int * kind)} 4606 4607@item @emph{Arguments}: 4608@multitable @columnfractions .15 .70 4609@item @var{team} @tab optional; team on the which the inquiry is to be 4610performed. 4611@item @var{image} @tab optional; the kind of the resulting integer array. 4612@end multitable 4613 4614@item @emph{NOTES} 4615This function follows TS18508. Because team-functionality is not yet 4616implemented a null-pointer is passed for the @var{team} argument at the moment. 4617@end table 4618 4619 4620@node _gfortran_caf_register 4621@subsection @code{_gfortran_caf_register} --- Registering coarrays 4622@cindex Coarray, _gfortran_caf_register 4623 4624@table @asis 4625@item @emph{Description}: 4626Registers memory for a coarray and creates a token to identify the coarray. The 4627routine is called for both coarrays with @code{SAVE} attribute and using an 4628explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a 4629@code{NULL} pointer, the function shall abort with printing an error message 4630and starting the error termination. If no error occurs and @var{STAT} is 4631present, it shall be set to zero. Otherwise, it shall be set to a positive 4632value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing 4633the failure. The routine shall register the memory provided in the 4634@code{DATA}-component of the array descriptor @var{DESC}, when that component 4635is non-@code{NULL}, else it shall allocate sufficient memory and provide a 4636pointer to it in the @code{DATA}-component of @var{DESC}. The array descriptor 4637has rank zero, when a scalar object is to be registered and the array 4638descriptor may be invalid after the call to @code{_gfortran_caf_register}. 4639When an array is to be allocated the descriptor persists. 4640 4641For @code{CAF_REGTYPE_COARRAY_STATIC} and @code{CAF_REGTYPE_COARRAY_ALLOC}, 4642the passed size is the byte size requested. For @code{CAF_REGTYPE_LOCK_STATIC}, 4643@code{CAF_REGTYPE_LOCK_ALLOC} and @code{CAF_REGTYPE_CRITICAL} it is the array 4644size or one for a scalar. 4645 4646When @code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} is used, then only a token 4647for an allocatable or pointer component is created. The @code{SIZE} parameter 4648is not used then. On the contrary when 4649@code{CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY} is specified, then the 4650@var{token} needs to be registered by a previous call with regtype 4651@code{CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY} and either the memory specified 4652in the @var{DESC}'s data-ptr is registered or allocate when the data-ptr is 4653@code{NULL}. 4654 4655@item @emph{Syntax}: 4656@code{void caf_register (size_t size, caf_register_t type, caf_token_t *token, 4657gfc_descriptor_t *desc, int *stat, char *errmsg, size_t errmsg_len)} 4658 4659@item @emph{Arguments}: 4660@multitable @columnfractions .15 .70 4661@item @var{size} @tab For normal coarrays, the byte size of the coarray to be 4662allocated; for lock types and event types, the number of elements. 4663@item @var{type} @tab one of the caf_register_t types. 4664@item @var{token} @tab intent(out) An opaque pointer identifying the coarray. 4665@item @var{desc} @tab intent(inout) The (pseudo) array descriptor. 4666@item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=; 4667may be @code{NULL} 4668@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 4669an error message; may be @code{NULL} 4670@item @var{errmsg_len} @tab the buffer size of errmsg. 4671@end multitable 4672 4673@item @emph{NOTES} 4674Nonallocatable coarrays have to be registered prior use from remote images. 4675In order to guarantee this, they have to be registered before the main 4676program. This can be achieved by creating constructor functions. That is what 4677GCC does such that also for nonallocatable coarrays the memory is allocated and 4678no static memory is used. The token permits to identify the coarray; to the 4679processor, the token is a nonaliasing pointer. The library can, for instance, 4680store the base address of the coarray in the token, some handle or a more 4681complicated struct. The library may also store the array descriptor 4682@var{DESC} when its rank is non-zero. 4683 4684For lock types, the value shall only be used for checking the allocation 4685status. Note that for critical blocks, the locking is only required on one 4686image; in the locking statement, the processor shall always pass an 4687image index of one for critical-block lock variables 4688(@code{CAF_REGTYPE_CRITICAL}). For lock types and critical-block variables, 4689the initial value shall be unlocked (or, respectively, not in critical 4690section) such as the value false; for event types, the initial state should 4691be no event, e.g. zero. 4692@end table 4693 4694 4695@node _gfortran_caf_deregister 4696@subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays 4697@cindex Coarray, _gfortran_caf_deregister 4698 4699@table @asis 4700@item @emph{Description}: 4701Called to free or deregister the memory of a coarray; the processor calls this 4702function for automatic and explicit deallocation. In case of an error, this 4703function shall fail with an error message, unless the @var{STAT} variable is 4704not null. The library is only expected to free memory it allocated itself 4705during a call to @code{_gfortran_caf_register}. 4706 4707@item @emph{Syntax}: 4708@code{void caf_deregister (caf_token_t *token, caf_deregister_t type, 4709int *stat, char *errmsg, size_t errmsg_len)} 4710 4711@item @emph{Arguments}: 4712@multitable @columnfractions .15 .70 4713@item @var{token} @tab the token to free. 4714@item @var{type} @tab the type of action to take for the coarray. A 4715@code{CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY} is allowed only for allocatable or 4716pointer components of derived type coarrays. The action only deallocates the 4717local memory without deleting the token. 4718@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL 4719@item @var{errmsg} @tab intent(out) When an error occurs, this will be set 4720to an error message; may be NULL 4721@item @var{errmsg_len} @tab the buffer size of errmsg. 4722@end multitable 4723 4724@item @emph{NOTES} 4725For nonalloatable coarrays this function is never called. If a cleanup is 4726required, it has to be handled via the finish, stop and error stop functions, 4727and via destructors. 4728@end table 4729 4730 4731@node _gfortran_caf_is_present 4732@subsection @code{_gfortran_caf_is_present} --- Query whether an allocatable or pointer component in a derived type coarray is allocated 4733@cindex Coarray, _gfortran_caf_is_present 4734 4735@table @asis 4736@item @emph{Description}: 4737Used to query the coarray library whether an allocatable component in a derived 4738type coarray is allocated on a remote image. 4739 4740@item @emph{Syntax}: 4741@code{void _gfortran_caf_is_present (caf_token_t token, int image_index, 4742gfc_reference_t *ref)} 4743 4744@item @emph{Arguments}: 4745@multitable @columnfractions .15 .70 4746@item @var{token} @tab An opaque pointer identifying the coarray. 4747@item @var{image_index} @tab The ID of the remote image; must be a positive 4748number. 4749@item @var{ref} @tab A chain of references to address the allocatable or 4750pointer component in the derived type coarray. The object reference needs to be 4751a scalar or a full array reference, respectively. 4752@end multitable 4753 4754@end table 4755 4756@node _gfortran_caf_send 4757@subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image 4758@cindex Coarray, _gfortran_caf_send 4759 4760@table @asis 4761@item @emph{Description}: 4762Called to send a scalar, an array section or a whole array from a local 4763to a remote image identified by the image_index. 4764 4765@item @emph{Syntax}: 4766@code{void _gfortran_caf_send (caf_token_t token, size_t offset, 4767int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector, 4768gfc_descriptor_t *src, int dst_kind, int src_kind, bool may_require_tmp, 4769int *stat)} 4770 4771@item @emph{Arguments}: 4772@multitable @columnfractions .15 .70 4773@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 4774@item @var{offset} @tab intent(in) By which amount of bytes the actual data is 4775shifted compared to the base address of the coarray. 4776@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 4777positive number. 4778@item @var{dest} @tab intent(in) Array descriptor for the remote image for the 4779bounds and the size. The @code{base_addr} shall not be accessed. 4780@item @var{dst_vector} @tab intent(in) If not NULL, it contains the vector 4781subscript of the destination array; the values are relative to the dimension 4782triplet of the dest argument. 4783@item @var{src} @tab intent(in) Array descriptor of the local array to be 4784transferred to the remote image 4785@item @var{dst_kind} @tab intent(in) Kind of the destination argument 4786@item @var{src_kind} @tab intent(in) Kind of the source argument 4787@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when 4788it is known at compile time that the @var{dest} and @var{src} either cannot 4789overlap or overlap (fully or partially) such that walking @var{src} and 4790@var{dest} in element wise element order (honoring the stride value) will not 4791lead to wrong results. Otherwise, the value is @code{true}. 4792@item @var{stat} @tab intent(out) when non-NULL give the result of the 4793operation, i.e., zero on success and non-zero on error. When NULL and an error 4794occurs, then an error message is printed and the program is terminated. 4795@end multitable 4796 4797@item @emph{NOTES} 4798It is permitted to have @var{image_index} equal the current image; the memory 4799of the send-to and the send-from might (partially) overlap in that case. The 4800implementation has to take care that it handles this case, e.g. using 4801@code{memmove} which handles (partially) overlapping memory. If 4802@var{may_require_tmp} is true, the library might additionally create a 4803temporary variable, unless additional checks show that this is not required 4804(e.g. because walking backward is possible or because both arrays are 4805contiguous and @code{memmove} takes care of overlap issues). 4806 4807Note that the assignment of a scalar to an array is permitted. In addition, 4808the library has to handle numeric-type conversion and for strings, padding 4809and different character kinds. 4810@end table 4811 4812 4813@node _gfortran_caf_get 4814@subsection @code{_gfortran_caf_get} --- Getting data from a remote image 4815@cindex Coarray, _gfortran_caf_get 4816 4817@table @asis 4818@item @emph{Description}: 4819Called to get an array section or a whole array from a remote, 4820image identified by the image_index. 4821 4822@item @emph{Syntax}: 4823@code{void _gfortran_caf_get (caf_token_t token, size_t offset, 4824int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector, 4825gfc_descriptor_t *dest, int src_kind, int dst_kind, bool may_require_tmp, 4826int *stat)} 4827 4828@item @emph{Arguments}: 4829@multitable @columnfractions .15 .70 4830@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 4831@item @var{offset} @tab intent(in) By which amount of bytes the actual data is 4832shifted compared to the base address of the coarray. 4833@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 4834positive number. 4835@item @var{dest} @tab intent(out) Array descriptor of the local array to store 4836the data retrieved from the remote image 4837@item @var{src} @tab intent(in) Array descriptor for the remote image for the 4838bounds and the size. The @code{base_addr} shall not be accessed. 4839@item @var{src_vector} @tab intent(in) If not NULL, it contains the vector 4840subscript of the source array; the values are relative to the dimension 4841triplet of the @var{src} argument. 4842@item @var{dst_kind} @tab intent(in) Kind of the destination argument 4843@item @var{src_kind} @tab intent(in) Kind of the source argument 4844@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when 4845it is known at compile time that the @var{dest} and @var{src} either cannot 4846overlap or overlap (fully or partially) such that walking @var{src} and 4847@var{dest} in element wise element order (honoring the stride value) will not 4848lead to wrong results. Otherwise, the value is @code{true}. 4849@item @var{stat} @tab intent(out) When non-NULL give the result of the 4850operation, i.e., zero on success and non-zero on error. When NULL and an error 4851occurs, then an error message is printed and the program is terminated. 4852@end multitable 4853 4854@item @emph{NOTES} 4855It is permitted to have @var{image_index} equal the current image; the memory of 4856the send-to and the send-from might (partially) overlap in that case. The 4857implementation has to take care that it handles this case, e.g. using 4858@code{memmove} which handles (partially) overlapping memory. If 4859@var{may_require_tmp} is true, the library might additionally create a 4860temporary variable, unless additional checks show that this is not required 4861(e.g. because walking backward is possible or because both arrays are 4862contiguous and @code{memmove} takes care of overlap issues). 4863 4864Note that the library has to handle numeric-type conversion and for strings, 4865padding and different character kinds. 4866@end table 4867 4868 4869@node _gfortran_caf_sendget 4870@subsection @code{_gfortran_caf_sendget} --- Sending data between remote images 4871@cindex Coarray, _gfortran_caf_sendget 4872 4873@table @asis 4874@item @emph{Description}: 4875Called to send a scalar, an array section or a whole array from a remote image 4876identified by the @var{src_image_index} to a remote image identified by the 4877@var{dst_image_index}. 4878 4879@item @emph{Syntax}: 4880@code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset, 4881int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector, 4882caf_token_t src_token, size_t src_offset, int src_image_index, 4883gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind, 4884bool may_require_tmp, int *stat)} 4885 4886@item @emph{Arguments}: 4887@multitable @columnfractions .15 .70 4888@item @var{dst_token} @tab intent(in) An opaque pointer identifying the 4889destination coarray. 4890@item @var{dst_offset} @tab intent(in) By which amount of bytes the actual data 4891is shifted compared to the base address of the destination coarray. 4892@item @var{dst_image_index} @tab intent(in) The ID of the destination remote 4893image; must be a positive number. 4894@item @var{dest} @tab intent(in) Array descriptor for the destination 4895remote image for the bounds and the size. The @code{base_addr} shall not be 4896accessed. 4897@item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector 4898subscript of the destination array; the values are relative to the dimension 4899triplet of the @var{dest} argument. 4900@item @var{src_token} @tab intent(in) An opaque pointer identifying the source 4901coarray. 4902@item @var{src_offset} @tab intent(in) By which amount of bytes the actual data 4903is shifted compared to the base address of the source coarray. 4904@item @var{src_image_index} @tab intent(in) The ID of the source remote image; 4905must be a positive number. 4906@item @var{src} @tab intent(in) Array descriptor of the local array to be 4907transferred to the remote image. 4908@item @var{src_vector} @tab intent(in) Array descriptor of the local array to 4909be transferred to the remote image 4910@item @var{dst_kind} @tab intent(in) Kind of the destination argument 4911@item @var{src_kind} @tab intent(in) Kind of the source argument 4912@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when 4913it is known at compile time that the @var{dest} and @var{src} either cannot 4914overlap or overlap (fully or partially) such that walking @var{src} and 4915@var{dest} in element wise element order (honoring the stride value) will not 4916lead to wrong results. Otherwise, the value is @code{true}. 4917@item @var{stat} @tab intent(out) when non-NULL give the result of the 4918operation, i.e., zero on success and non-zero on error. When NULL and an error 4919occurs, then an error message is printed and the program is terminated. 4920@end multitable 4921 4922@item @emph{NOTES} 4923It is permitted to have the same image index for both @var{src_image_index} and 4924@var{dst_image_index}; the memory of the send-to and the send-from might 4925(partially) overlap in that case. The implementation has to take care that it 4926handles this case, e.g. using @code{memmove} which handles (partially) 4927overlapping memory. If @var{may_require_tmp} is true, the library 4928might additionally create a temporary variable, unless additional checks show 4929that this is not required (e.g. because walking backward is possible or because 4930both arrays are contiguous and @code{memmove} takes care of overlap issues). 4931 4932Note that the assignment of a scalar to an array is permitted. In addition, 4933the library has to handle numeric-type conversion and for strings, padding and 4934different character kinds. 4935@end table 4936 4937@node _gfortran_caf_send_by_ref 4938@subsection @code{_gfortran_caf_send_by_ref} --- Sending data from a local image to a remote image with enhanced referencing options 4939@cindex Coarray, _gfortran_caf_send_by_ref 4940 4941@table @asis 4942@item @emph{Description}: 4943Called to send a scalar, an array section or a whole array from a local to a 4944remote image identified by the @var{image_index}. 4945 4946@item @emph{Syntax}: 4947@code{void _gfortran_caf_send_by_ref (caf_token_t token, int image_index, 4948gfc_descriptor_t *src, caf_reference_t *refs, int dst_kind, int src_kind, 4949bool may_require_tmp, bool dst_reallocatable, int *stat, int dst_type)} 4950 4951@item @emph{Arguments}: 4952@multitable @columnfractions .15 .70 4953@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 4954@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 4955positive number. 4956@item @var{src} @tab intent(in) Array descriptor of the local array to be 4957transferred to the remote image 4958@item @var{refs} @tab intent(in) The references on the remote array to store 4959the data given by src. Guaranteed to have at least one entry. 4960@item @var{dst_kind} @tab intent(in) Kind of the destination argument 4961@item @var{src_kind} @tab intent(in) Kind of the source argument 4962@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when 4963it is known at compile time that the @var{dest} and @var{src} either cannot 4964overlap or overlap (fully or partially) such that walking @var{src} and 4965@var{dest} in element wise element order (honoring the stride value) will not 4966lead to wrong results. Otherwise, the value is @code{true}. 4967@item @var{dst_reallocatable} @tab intent(in) Set when the destination is of 4968allocatable or pointer type and the refs will allow reallocation, i.e., the ref 4969is a full array or component ref. 4970@item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the 4971operation, i.e., zero on success and non-zero on error. When @code{NULL} and 4972an error occurs, then an error message is printed and the program is terminated. 4973@item @var{dst_type} @tab intent(in) Give the type of the destination. When 4974the destination is not an array, than the precise type, e.g. of a component in 4975a derived type, is not known, but provided here. 4976@end multitable 4977 4978@item @emph{NOTES} 4979It is permitted to have @var{image_index} equal the current image; the memory of 4980the send-to and the send-from might (partially) overlap in that case. The 4981implementation has to take care that it handles this case, e.g. using 4982@code{memmove} which handles (partially) overlapping memory. If 4983@var{may_require_tmp} is true, the library might additionally create a 4984temporary variable, unless additional checks show that this is not required 4985(e.g. because walking backward is possible or because both arrays are 4986contiguous and @code{memmove} takes care of overlap issues). 4987 4988Note that the assignment of a scalar to an array is permitted. In addition, 4989the library has to handle numeric-type conversion and for strings, padding 4990and different character kinds. 4991 4992Because of the more complicated references possible some operations may be 4993unsupported by certain libraries. The library is expected to issue a precise 4994error message why the operation is not permitted. 4995@end table 4996 4997 4998@node _gfortran_caf_get_by_ref 4999@subsection @code{_gfortran_caf_get_by_ref} --- Getting data from a remote image using enhanced references 5000@cindex Coarray, _gfortran_caf_get_by_ref 5001 5002@table @asis 5003@item @emph{Description}: 5004Called to get a scalar, an array section or a whole array from a remote image 5005identified by the @var{image_index}. 5006 5007@item @emph{Syntax}: 5008@code{void _gfortran_caf_get_by_ref (caf_token_t token, int image_index, 5009caf_reference_t *refs, gfc_descriptor_t *dst, int dst_kind, int src_kind, 5010bool may_require_tmp, bool dst_reallocatable, int *stat, int src_type)} 5011 5012@item @emph{Arguments}: 5013@multitable @columnfractions .15 .70 5014@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 5015@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 5016positive number. 5017@item @var{refs} @tab intent(in) The references to apply to the remote structure 5018to get the data. 5019@item @var{dst} @tab intent(in) Array descriptor of the local array to store 5020the data transferred from the remote image. May be reallocated where needed 5021and when @var{DST_REALLOCATABLE} allows it. 5022@item @var{dst_kind} @tab intent(in) Kind of the destination argument 5023@item @var{src_kind} @tab intent(in) Kind of the source argument 5024@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when 5025it is known at compile time that the @var{dest} and @var{src} either cannot 5026overlap or overlap (fully or partially) such that walking @var{src} and 5027@var{dest} in element wise element order (honoring the stride value) will not 5028lead to wrong results. Otherwise, the value is @code{true}. 5029@item @var{dst_reallocatable} @tab intent(in) Set when @var{DST} is of 5030allocatable or pointer type and its refs allow reallocation, i.e., the full 5031array or a component is referenced. 5032@item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the 5033operation, i.e., zero on success and non-zero on error. When @code{NULL} and an 5034error occurs, then an error message is printed and the program is terminated. 5035@item @var{src_type} @tab intent(in) Give the type of the source. When the 5036source is not an array, than the precise type, e.g. of a component in a 5037derived type, is not known, but provided here. 5038@end multitable 5039 5040@item @emph{NOTES} 5041It is permitted to have @code{image_index} equal the current image; the memory 5042of the send-to and the send-from might (partially) overlap in that case. The 5043implementation has to take care that it handles this case, e.g. using 5044@code{memmove} which handles (partially) overlapping memory. If 5045@var{may_require_tmp} is true, the library might additionally create a 5046temporary variable, unless additional checks show that this is not required 5047(e.g. because walking backward is possible or because both arrays are 5048contiguous and @code{memmove} takes care of overlap issues). 5049 5050Note that the library has to handle numeric-type conversion and for strings, 5051padding and different character kinds. 5052 5053Because of the more complicated references possible some operations may be 5054unsupported by certain libraries. The library is expected to issue a precise 5055error message why the operation is not permitted. 5056@end table 5057 5058 5059@node _gfortran_caf_sendget_by_ref 5060@subsection @code{_gfortran_caf_sendget_by_ref} --- Sending data between remote images using enhanced references on both sides 5061@cindex Coarray, _gfortran_caf_sendget_by_ref 5062 5063@table @asis 5064@item @emph{Description}: 5065Called to send a scalar, an array section or a whole array from a remote image 5066identified by the @var{src_image_index} to a remote image identified by the 5067@var{dst_image_index}. 5068 5069@item @emph{Syntax}: 5070@code{void _gfortran_caf_sendget_by_ref (caf_token_t dst_token, 5071int dst_image_index, caf_reference_t *dst_refs, 5072caf_token_t src_token, int src_image_index, caf_reference_t *src_refs, 5073int dst_kind, int src_kind, bool may_require_tmp, int *dst_stat, 5074int *src_stat, int dst_type, int src_type)} 5075 5076@item @emph{Arguments}: 5077@multitable @columnfractions .15 .70 5078@item @var{dst_token} @tab intent(in) An opaque pointer identifying the 5079destination coarray. 5080@item @var{dst_image_index} @tab intent(in) The ID of the destination remote 5081image; must be a positive number. 5082@item @var{dst_refs} @tab intent(in) The references on the remote array to store 5083the data given by the source. Guaranteed to have at least one entry. 5084@item @var{src_token} @tab intent(in) An opaque pointer identifying the source 5085coarray. 5086@item @var{src_image_index} @tab intent(in) The ID of the source remote image; 5087must be a positive number. 5088@item @var{src_refs} @tab intent(in) The references to apply to the remote 5089structure to get the data. 5090@item @var{dst_kind} @tab intent(in) Kind of the destination argument 5091@item @var{src_kind} @tab intent(in) Kind of the source argument 5092@item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when 5093it is known at compile time that the @var{dest} and @var{src} either cannot 5094overlap or overlap (fully or partially) such that walking @var{src} and 5095@var{dest} in element wise element order (honoring the stride value) will not 5096lead to wrong results. Otherwise, the value is @code{true}. 5097@item @var{dst_stat} @tab intent(out) when non-@code{NULL} give the result of 5098the send-operation, i.e., zero on success and non-zero on error. When 5099@code{NULL} and an error occurs, then an error message is printed and the 5100program is terminated. 5101@item @var{src_stat} @tab intent(out) When non-@code{NULL} give the result of 5102the get-operation, i.e., zero on success and non-zero on error. When 5103@code{NULL} and an error occurs, then an error message is printed and the 5104program is terminated. 5105@item @var{dst_type} @tab intent(in) Give the type of the destination. When 5106the destination is not an array, than the precise type, e.g. of a component in 5107a derived type, is not known, but provided here. 5108@item @var{src_type} @tab intent(in) Give the type of the source. When the 5109source is not an array, than the precise type, e.g. of a component in a 5110derived type, is not known, but provided here. 5111@end multitable 5112 5113@item @emph{NOTES} 5114It is permitted to have the same image index for both @var{src_image_index} and 5115@var{dst_image_index}; the memory of the send-to and the send-from might 5116(partially) overlap in that case. The implementation has to take care that it 5117handles this case, e.g. using @code{memmove} which handles (partially) 5118overlapping memory. If @var{may_require_tmp} is true, the library 5119might additionally create a temporary variable, unless additional checks show 5120that this is not required (e.g. because walking backward is possible or because 5121both arrays are contiguous and @code{memmove} takes care of overlap issues). 5122 5123Note that the assignment of a scalar to an array is permitted. In addition, 5124the library has to handle numeric-type conversion and for strings, padding and 5125different character kinds. 5126 5127Because of the more complicated references possible some operations may be 5128unsupported by certain libraries. The library is expected to issue a precise 5129error message why the operation is not permitted. 5130@end table 5131 5132 5133@node _gfortran_caf_lock 5134@subsection @code{_gfortran_caf_lock} --- Locking a lock variable 5135@cindex Coarray, _gfortran_caf_lock 5136 5137@table @asis 5138@item @emph{Description}: 5139Acquire a lock on the given image on a scalar locking variable or for the 5140given array element for an array-valued variable. If the @var{acquired_lock} 5141is @code{NULL}, the function returns after having obtained the lock. If it is 5142non-@code{NULL}, then @var{acquired_lock} is assigned the value true (one) when 5143the lock could be obtained and false (zero) otherwise. Locking a lock variable 5144which has already been locked by the same image is an error. 5145 5146@item @emph{Syntax}: 5147@code{void _gfortran_caf_lock (caf_token_t token, size_t index, int image_index, 5148int *acquired_lock, int *stat, char *errmsg, size_t errmsg_len)} 5149 5150@item @emph{Arguments}: 5151@multitable @columnfractions .15 .70 5152@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 5153@item @var{index} @tab intent(in) Array index; first array index is 0. For 5154scalars, it is always 0. 5155@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 5156positive number. 5157@item @var{acquired_lock} @tab intent(out) If not NULL, it returns whether lock 5158could be obtained. 5159@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL. 5160@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5161an error message; may be NULL. 5162@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5163@end multitable 5164 5165@item @emph{NOTES} 5166This function is also called for critical blocks; for those, the array index 5167is always zero and the image index is one. Libraries are permitted to use other 5168images for critical-block locking variables. 5169@end table 5170 5171@node _gfortran_caf_unlock 5172@subsection @code{_gfortran_caf_lock} --- Unlocking a lock variable 5173@cindex Coarray, _gfortran_caf_unlock 5174 5175@table @asis 5176@item @emph{Description}: 5177Release a lock on the given image on a scalar locking variable or for the 5178given array element for an array-valued variable. Unlocking a lock variable 5179which is unlocked or has been locked by a different image is an error. 5180 5181@item @emph{Syntax}: 5182@code{void _gfortran_caf_unlock (caf_token_t token, size_t index, int image_index, 5183int *stat, char *errmsg, size_t errmsg_len)} 5184 5185@item @emph{Arguments}: 5186@multitable @columnfractions .15 .70 5187@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 5188@item @var{index} @tab intent(in) Array index; first array index is 0. For 5189scalars, it is always 0. 5190@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 5191positive number. 5192@item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=; 5193may be NULL. 5194@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5195an error message; may be NULL. 5196@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5197@end multitable 5198 5199@item @emph{NOTES} 5200This function is also called for critical block; for those, the array index 5201is always zero and the image index is one. Libraries are permitted to use other 5202images for critical-block locking variables. 5203@end table 5204 5205@node _gfortran_caf_event_post 5206@subsection @code{_gfortran_caf_event_post} --- Post an event 5207@cindex Coarray, _gfortran_caf_event_post 5208 5209@table @asis 5210@item @emph{Description}: 5211Increment the event count of the specified event variable. 5212 5213@item @emph{Syntax}: 5214@code{void _gfortran_caf_event_post (caf_token_t token, size_t index, 5215int image_index, int *stat, char *errmsg, size_t errmsg_len)} 5216 5217@item @emph{Arguments}: 5218@multitable @columnfractions .15 .70 5219@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 5220@item @var{index} @tab intent(in) Array index; first array index is 0. For 5221scalars, it is always 0. 5222@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 5223positive number; zero indicates the current image, when accessed noncoindexed. 5224@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL. 5225@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5226an error message; may be NULL. 5227@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5228@end multitable 5229 5230@item @emph{NOTES} 5231This acts like an atomic add of one to the remote image's event variable. 5232The statement is an image-control statement but does not imply sync memory. 5233Still, all preceeding push communications of this image to the specified 5234remote image have to be completed before @code{event_wait} on the remote 5235image returns. 5236@end table 5237 5238 5239 5240@node _gfortran_caf_event_wait 5241@subsection @code{_gfortran_caf_event_wait} --- Wait that an event occurred 5242@cindex Coarray, _gfortran_caf_event_wait 5243 5244@table @asis 5245@item @emph{Description}: 5246Wait until the event count has reached at least the specified 5247@var{until_count}; if so, atomically decrement the event variable by this 5248amount and return. 5249 5250@item @emph{Syntax}: 5251@code{void _gfortran_caf_event_wait (caf_token_t token, size_t index, 5252int until_count, int *stat, char *errmsg, size_t errmsg_len)} 5253 5254@item @emph{Arguments}: 5255@multitable @columnfractions .15 .70 5256@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 5257@item @var{index} @tab intent(in) Array index; first array index is 0. For 5258scalars, it is always 0. 5259@item @var{until_count} @tab intent(in) The number of events which have to be 5260available before the function returns. 5261@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL. 5262@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5263an error message; may be NULL. 5264@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5265@end multitable 5266 5267@item @emph{NOTES} 5268This function only operates on a local coarray. It acts like a loop checking 5269atomically the value of the event variable, breaking if the value is greater 5270or equal the requested number of counts. Before the function returns, the 5271event variable has to be decremented by the requested @var{until_count} value. 5272A possible implementation would be a busy loop for a certain number of spins 5273(possibly depending on the number of threads relative to the number of available 5274cores) followed by another waiting strategy such as a sleeping wait (possibly 5275with an increasing number of sleep time) or, if possible, a futex wait. 5276 5277The statement is an image-control statement but does not imply sync memory. 5278Still, all preceeding push communications of this image to the specified 5279remote image have to be completed before @code{event_wait} on the remote 5280image returns. 5281@end table 5282 5283 5284 5285@node _gfortran_caf_event_query 5286@subsection @code{_gfortran_caf_event_query} --- Query event count 5287@cindex Coarray, _gfortran_caf_event_query 5288 5289@table @asis 5290@item @emph{Description}: 5291Return the event count of the specified event variable. 5292 5293@item @emph{Syntax}: 5294@code{void _gfortran_caf_event_query (caf_token_t token, size_t index, 5295int image_index, int *count, int *stat)} 5296 5297@item @emph{Arguments}: 5298@multitable @columnfractions .15 .70 5299@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 5300@item @var{index} @tab intent(in) Array index; first array index is 0. For 5301scalars, it is always 0. 5302@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 5303positive number; zero indicates the current image when accessed noncoindexed. 5304@item @var{count} @tab intent(out) The number of events currently posted to 5305the event variable. 5306@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL. 5307@end multitable 5308 5309@item @emph{NOTES} 5310The typical use is to check the local event variable to only call 5311@code{event_wait} when the data is available. However, a coindexed variable 5312is permitted; there is no ordering or synchronization implied. It acts like 5313an atomic fetch of the value of the event variable. 5314@end table 5315 5316 5317 5318@node _gfortran_caf_sync_all 5319@subsection @code{_gfortran_caf_sync_all} --- All-image barrier 5320@cindex Coarray, _gfortran_caf_sync_all 5321 5322@table @asis 5323@item @emph{Description}: 5324Synchronization of all images in the current team; the program only continues 5325on a given image after this function has been called on all images of the 5326current team. Additionally, it ensures that all pending data transfers of 5327previous segment have completed. 5328 5329@item @emph{Syntax}: 5330@code{void _gfortran_caf_sync_all (int *stat, char *errmsg, size_t errmsg_len)} 5331 5332@item @emph{Arguments}: 5333@multitable @columnfractions .15 .70 5334@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5335@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5336an error message; may be NULL. 5337@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5338@end multitable 5339@end table 5340 5341 5342 5343@node _gfortran_caf_sync_images 5344@subsection @code{_gfortran_caf_sync_images} --- Barrier for selected images 5345@cindex Coarray, _gfortran_caf_sync_images 5346 5347@table @asis 5348@item @emph{Description}: 5349Synchronization between the specified images; the program only continues on a 5350given image after this function has been called on all images specified for 5351that image. Note that one image can wait for all other images in the current 5352team (e.g. via @code{sync images(*)}) while those only wait for that specific 5353image. Additionally, @code{sync images} ensures that all pending data 5354transfers of previous segments have completed. 5355 5356@item @emph{Syntax}: 5357@code{void _gfortran_caf_sync_images (int count, int images[], int *stat, 5358char *errmsg, size_t errmsg_len)} 5359 5360@item @emph{Arguments}: 5361@multitable @columnfractions .15 .70 5362@item @var{count} @tab intent(in) The number of images which are provided in 5363the next argument. For a zero-sized array, the value is zero. For 5364@code{sync images (*)}, the value is @math{-1}. 5365@item @var{images} @tab intent(in) An array with the images provided by the 5366user. If @var{count} is zero, a NULL pointer is passed. 5367@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5368@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5369an error message; may be NULL. 5370@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5371@end multitable 5372@end table 5373 5374 5375 5376@node _gfortran_caf_sync_memory 5377@subsection @code{_gfortran_caf_sync_memory} --- Wait for completion of segment-memory operations 5378@cindex Coarray, _gfortran_caf_sync_memory 5379 5380@table @asis 5381@item @emph{Description}: 5382Acts as optimization barrier between different segments. It also ensures that 5383all pending memory operations of this image have been completed. 5384 5385@item @emph{Syntax}: 5386@code{void _gfortran_caf_sync_memory (int *stat, char *errmsg, size_t errmsg_len)} 5387 5388@item @emph{Arguments}: 5389@multitable @columnfractions .15 .70 5390@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5391@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5392an error message; may be NULL. 5393@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5394@end multitable 5395 5396@item @emph{NOTE} A simple implementation could be 5397@code{__asm__ __volatile__ ("":::"memory")} to prevent code movements. 5398@end table 5399 5400 5401 5402@node _gfortran_caf_error_stop 5403@subsection @code{_gfortran_caf_error_stop} --- Error termination with exit code 5404@cindex Coarray, _gfortran_caf_error_stop 5405 5406@table @asis 5407@item @emph{Description}: 5408Invoked for an @code{ERROR STOP} statement which has an integer argument. The 5409function should terminate the program with the specified exit code. 5410 5411 5412@item @emph{Syntax}: 5413@code{void _gfortran_caf_error_stop (int error)} 5414 5415@item @emph{Arguments}: 5416@multitable @columnfractions .15 .70 5417@item @var{error} @tab intent(in) The exit status to be used. 5418@end multitable 5419@end table 5420 5421 5422 5423@node _gfortran_caf_error_stop_str 5424@subsection @code{_gfortran_caf_error_stop_str} --- Error termination with string 5425@cindex Coarray, _gfortran_caf_error_stop_str 5426 5427@table @asis 5428@item @emph{Description}: 5429Invoked for an @code{ERROR STOP} statement which has a string as argument. The 5430function should terminate the program with a nonzero-exit code. 5431 5432@item @emph{Syntax}: 5433@code{void _gfortran_caf_error_stop (const char *string, size_t len)} 5434 5435@item @emph{Arguments}: 5436@multitable @columnfractions .15 .70 5437@item @var{string} @tab intent(in) the error message (not zero terminated) 5438@item @var{len} @tab intent(in) the length of the string 5439@end multitable 5440@end table 5441 5442 5443 5444@node _gfortran_caf_fail_image 5445@subsection @code{_gfortran_caf_fail_image} --- Mark the image failed and end its execution 5446@cindex Coarray, _gfortran_caf_fail_image 5447 5448@table @asis 5449@item @emph{Description}: 5450Invoked for an @code{FAIL IMAGE} statement. The function should terminate the 5451current image. 5452 5453@item @emph{Syntax}: 5454@code{void _gfortran_caf_fail_image ()} 5455 5456@item @emph{NOTES} 5457This function follows TS18508. 5458@end table 5459 5460 5461 5462@node _gfortran_caf_atomic_define 5463@subsection @code{_gfortran_caf_atomic_define} --- Atomic variable assignment 5464@cindex Coarray, _gfortran_caf_atomic_define 5465 5466@table @asis 5467@item @emph{Description}: 5468Assign atomically a value to an integer or logical variable. 5469 5470@item @emph{Syntax}: 5471@code{void _gfortran_caf_atomic_define (caf_token_t token, size_t offset, 5472int image_index, void *value, int *stat, int type, int kind)} 5473 5474@item @emph{Arguments}: 5475@multitable @columnfractions .15 .70 5476@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 5477@item @var{offset} @tab intent(in) By which amount of bytes the actual data is 5478shifted compared to the base address of the coarray. 5479@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 5480positive number; zero indicates the current image when used noncoindexed. 5481@item @var{value} @tab intent(in) the value to be assigned, passed by reference 5482@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5483@item @var{type} @tab intent(in) The data type, i.e. @code{BT_INTEGER} (1) or 5484@code{BT_LOGICAL} (2). 5485@item @var{kind} @tab intent(in) The kind value (only 4; always @code{int}) 5486@end multitable 5487@end table 5488 5489 5490 5491@node _gfortran_caf_atomic_ref 5492@subsection @code{_gfortran_caf_atomic_ref} --- Atomic variable reference 5493@cindex Coarray, _gfortran_caf_atomic_ref 5494 5495@table @asis 5496@item @emph{Description}: 5497Reference atomically a value of a kind-4 integer or logical variable. 5498 5499@item @emph{Syntax}: 5500@code{void _gfortran_caf_atomic_ref (caf_token_t token, size_t offset, 5501int image_index, void *value, int *stat, int type, int kind)} 5502 5503@item @emph{Arguments}: 5504@multitable @columnfractions .15 .70 5505@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 5506@item @var{offset} @tab intent(in) By which amount of bytes the actual data is 5507shifted compared to the base address of the coarray. 5508@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 5509positive number; zero indicates the current image when used noncoindexed. 5510@item @var{value} @tab intent(out) The variable assigned the atomically 5511referenced variable. 5512@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5513@item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or 5514@code{BT_LOGICAL} (2). 5515@item @var{kind} @tab The kind value (only 4; always @code{int}) 5516@end multitable 5517@end table 5518 5519 5520 5521@node _gfortran_caf_atomic_cas 5522@subsection @code{_gfortran_caf_atomic_cas} --- Atomic compare and swap 5523@cindex Coarray, _gfortran_caf_atomic_cas 5524 5525@table @asis 5526@item @emph{Description}: 5527Atomic compare and swap of a kind-4 integer or logical variable. Assigns 5528atomically the specified value to the atomic variable, if the latter has 5529the value specified by the passed condition value. 5530 5531@item @emph{Syntax}: 5532@code{void _gfortran_caf_atomic_cas (caf_token_t token, size_t offset, 5533int image_index, void *old, void *compare, void *new_val, int *stat, 5534int type, int kind)} 5535 5536@item @emph{Arguments}: 5537@multitable @columnfractions .15 .70 5538@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 5539@item @var{offset} @tab intent(in) By which amount of bytes the actual data is 5540shifted compared to the base address of the coarray. 5541@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 5542positive number; zero indicates the current image when used noncoindexed. 5543@item @var{old} @tab intent(out) The value which the atomic variable had 5544just before the cas operation. 5545@item @var{compare} @tab intent(in) The value used for comparision. 5546@item @var{new_val} @tab intent(in) The new value for the atomic variable, 5547assigned to the atomic variable, if @code{compare} equals the value of the 5548atomic variable. 5549@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5550@item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or 5551@code{BT_LOGICAL} (2). 5552@item @var{kind} @tab intent(in) The kind value (only 4; always @code{int}) 5553@end multitable 5554@end table 5555 5556 5557 5558@node _gfortran_caf_atomic_op 5559@subsection @code{_gfortran_caf_atomic_op} --- Atomic operation 5560@cindex Coarray, _gfortran_caf_atomic_op 5561 5562@table @asis 5563@item @emph{Description}: 5564Apply an operation atomically to an atomic integer or logical variable. 5565After the operation, @var{old} contains the value just before the operation, 5566which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the @code{value} to 5567the atomic integer variable or does a bitwise AND, OR or exclusive OR 5568between the atomic variable and @var{value}; the result is then stored in the 5569atomic variable. 5570 5571@item @emph{Syntax}: 5572@code{void _gfortran_caf_atomic_op (int op, caf_token_t token, size_t offset, 5573int image_index, void *value, void *old, int *stat, int type, int kind)} 5574 5575@item @emph{Arguments}: 5576@multitable @columnfractions .15 .70 5577@item @var{op} @tab intent(in) the operation to be performed; possible values 5578@code{GFC_CAF_ATOMIC_ADD} (1), @code{GFC_CAF_ATOMIC_AND} (2), 5579@code{GFC_CAF_ATOMIC_OR} (3), @code{GFC_CAF_ATOMIC_XOR} (4). 5580@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. 5581@item @var{offset} @tab intent(in) By which amount of bytes the actual data is 5582shifted compared to the base address of the coarray. 5583@item @var{image_index} @tab intent(in) The ID of the remote image; must be a 5584positive number; zero indicates the current image when used noncoindexed. 5585@item @var{old} @tab intent(out) The value which the atomic variable had 5586just before the atomic operation. 5587@item @var{val} @tab intent(in) The new value for the atomic variable, 5588assigned to the atomic variable, if @code{compare} equals the value of the 5589atomic variable. 5590@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5591@item @var{type} @tab intent(in) the data type, i.e. @code{BT_INTEGER} (1) or 5592@code{BT_LOGICAL} (2) 5593@item @var{kind} @tab intent(in) the kind value (only 4; always @code{int}) 5594@end multitable 5595@end table 5596 5597 5598 5599 5600@node _gfortran_caf_co_broadcast 5601@subsection @code{_gfortran_caf_co_broadcast} --- Sending data to all images 5602@cindex Coarray, _gfortran_caf_co_broadcast 5603 5604@table @asis 5605@item @emph{Description}: 5606Distribute a value from a given image to all other images in the team. Has to 5607be called collectively. 5608 5609@item @emph{Syntax}: 5610@code{void _gfortran_caf_co_broadcast (gfc_descriptor_t *a, 5611int source_image, int *stat, char *errmsg, size_t errmsg_len)} 5612 5613@item @emph{Arguments}: 5614@multitable @columnfractions .15 .70 5615@item @var{a} @tab intent(inout) An array descriptor with the data to be 5616broadcasted (on @var{source_image}) or to be received (other images). 5617@item @var{source_image} @tab intent(in) The ID of the image from which the 5618data should be broadcasted. 5619@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5620@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5621an error message; may be NULL. 5622@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg. 5623@end multitable 5624@end table 5625 5626 5627 5628@node _gfortran_caf_co_max 5629@subsection @code{_gfortran_caf_co_max} --- Collective maximum reduction 5630@cindex Coarray, _gfortran_caf_co_max 5631 5632@table @asis 5633@item @emph{Description}: 5634Calculates for each array element of the variable @var{a} the maximum 5635value for that element in the current team; if @var{result_image} has the 5636value 0, the result shall be stored on all images, otherwise, only on the 5637specified image. This function operates on numeric values and character 5638strings. 5639 5640@item @emph{Syntax}: 5641@code{void _gfortran_caf_co_max (gfc_descriptor_t *a, int result_image, 5642int *stat, char *errmsg, int a_len, size_t errmsg_len)} 5643 5644@item @emph{Arguments}: 5645@multitable @columnfractions .15 .70 5646@item @var{a} @tab intent(inout) An array descriptor for the data to be 5647processed. On the destination image(s) the result overwrites the old content. 5648@item @var{result_image} @tab intent(in) The ID of the image to which the 5649reduced value should be copied to; if zero, it has to be copied to all images. 5650@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5651@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5652an error message; may be NULL. 5653@item @var{a_len} @tab intent(in) the string length of argument @var{a} 5654@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5655@end multitable 5656 5657@item @emph{NOTES} 5658If @var{result_image} is nonzero, the data in the array descriptor @var{a} on 5659all images except of the specified one become undefined; hence, the library may 5660make use of this. 5661@end table 5662 5663 5664 5665@node _gfortran_caf_co_min 5666@subsection @code{_gfortran_caf_co_min} --- Collective minimum reduction 5667@cindex Coarray, _gfortran_caf_co_min 5668 5669@table @asis 5670@item @emph{Description}: 5671Calculates for each array element of the variable @var{a} the minimum 5672value for that element in the current team; if @var{result_image} has the 5673value 0, the result shall be stored on all images, otherwise, only on the 5674specified image. This function operates on numeric values and character 5675strings. 5676 5677@item @emph{Syntax}: 5678@code{void _gfortran_caf_co_min (gfc_descriptor_t *a, int result_image, 5679int *stat, char *errmsg, int a_len, size_t errmsg_len)} 5680 5681@item @emph{Arguments}: 5682@multitable @columnfractions .15 .70 5683@item @var{a} @tab intent(inout) An array descriptor for the data to be 5684processed. On the destination image(s) the result overwrites the old content. 5685@item @var{result_image} @tab intent(in) The ID of the image to which the 5686reduced value should be copied to; if zero, it has to be copied to all images. 5687@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5688@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5689an error message; may be NULL. 5690@item @var{a_len} @tab intent(in) the string length of argument @var{a} 5691@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5692@end multitable 5693 5694@item @emph{NOTES} 5695If @var{result_image} is nonzero, the data in the array descriptor @var{a} on 5696all images except of the specified one become undefined; hence, the library may 5697make use of this. 5698@end table 5699 5700 5701 5702@node _gfortran_caf_co_sum 5703@subsection @code{_gfortran_caf_co_sum} --- Collective summing reduction 5704@cindex Coarray, _gfortran_caf_co_sum 5705 5706@table @asis 5707@item @emph{Description}: 5708Calculates for each array element of the variable @var{a} the sum of all 5709values for that element in the current team; if @var{result_image} has the 5710value 0, the result shall be stored on all images, otherwise, only on the 5711specified image. This function operates on numeric values only. 5712 5713@item @emph{Syntax}: 5714@code{void _gfortran_caf_co_sum (gfc_descriptor_t *a, int result_image, 5715int *stat, char *errmsg, size_t errmsg_len)} 5716 5717@item @emph{Arguments}: 5718@multitable @columnfractions .15 .70 5719@item @var{a} @tab intent(inout) An array descriptor with the data to be 5720processed. On the destination image(s) the result overwrites the old content. 5721@item @var{result_image} @tab intent(in) The ID of the image to which the 5722reduced value should be copied to; if zero, it has to be copied to all images. 5723@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5724@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5725an error message; may be NULL. 5726@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5727@end multitable 5728 5729@item @emph{NOTES} 5730If @var{result_image} is nonzero, the data in the array descriptor @var{a} on 5731all images except of the specified one become undefined; hence, the library may 5732make use of this. 5733@end table 5734 5735 5736 5737@node _gfortran_caf_co_reduce 5738@subsection @code{_gfortran_caf_co_reduce} --- Generic collective reduction 5739@cindex Coarray, _gfortran_caf_co_reduce 5740 5741@table @asis 5742@item @emph{Description}: 5743Calculates for each array element of the variable @var{a} the reduction 5744value for that element in the current team; if @var{result_image} has the 5745value 0, the result shall be stored on all images, otherwise, only on the 5746specified image. The @var{opr} is a pure function doing a mathematically 5747commutative and associative operation. 5748 5749The @var{opr_flags} denote the following; the values are bitwise ored. 5750@code{GFC_CAF_BYREF} (1) if the result should be returned 5751by reference; @code{GFC_CAF_HIDDENLEN} (2) whether the result and argument 5752string lengths shall be specified as hidden arguments; 5753@code{GFC_CAF_ARG_VALUE} (4) whether the arguments shall be passed by value, 5754@code{GFC_CAF_ARG_DESC} (8) whether the arguments shall be passed by descriptor. 5755 5756 5757@item @emph{Syntax}: 5758@code{void _gfortran_caf_co_reduce (gfc_descriptor_t *a, 5759void * (*opr) (void *, void *), int opr_flags, int result_image, 5760int *stat, char *errmsg, int a_len, size_t errmsg_len)} 5761 5762@item @emph{Arguments}: 5763@multitable @columnfractions .15 .70 5764@item @var{a} @tab intent(inout) An array descriptor with the data to be 5765processed. On the destination image(s) the result overwrites the old content. 5766@item @var{opr} @tab intent(in) Function pointer to the reduction function 5767@item @var{opr_flags} @tab intent(in) Flags regarding the reduction function 5768@item @var{result_image} @tab intent(in) The ID of the image to which the 5769reduced value should be copied to; if zero, it has to be copied to all images. 5770@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. 5771@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to 5772an error message; may be NULL. 5773@item @var{a_len} @tab intent(in) the string length of argument @var{a} 5774@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg 5775@end multitable 5776 5777@item @emph{NOTES} 5778If @var{result_image} is nonzero, the data in the array descriptor @var{a} on 5779all images except of the specified one become undefined; hence, the library may 5780make use of this. 5781 5782For character arguments, the result is passed as first argument, followed 5783by the result string length, next come the two string arguments, followed 5784by the two hidden string length arguments. With C binding, there are no hidden 5785arguments and by-reference passing and either only a single character is passed 5786or an array descriptor. 5787@end table 5788 5789 5790@c Intrinsic Procedures 5791@c --------------------------------------------------------------------- 5792 5793@include intrinsic.texi 5794 5795 5796@tex 5797\blankpart 5798@end tex 5799 5800@c --------------------------------------------------------------------- 5801@c Contributing 5802@c --------------------------------------------------------------------- 5803 5804@node Contributing 5805@unnumbered Contributing 5806@cindex Contributing 5807 5808Free software is only possible if people contribute to efforts 5809to create it. 5810We're always in need of more people helping out with ideas 5811and comments, writing documentation and contributing code. 5812 5813If you want to contribute to GNU Fortran, 5814have a look at the long lists of projects you can take on. 5815Some of these projects are small, 5816some of them are large; 5817some are completely orthogonal to the rest of what is 5818happening on GNU Fortran, 5819but others are ``mainstream'' projects in need of enthusiastic hackers. 5820All of these projects are important! 5821We will eventually get around to the things here, 5822but they are also things doable by someone who is willing and able. 5823 5824@menu 5825* Contributors:: 5826* Projects:: 5827* Proposed Extensions:: 5828@end menu 5829 5830 5831@node Contributors 5832@section Contributors to GNU Fortran 5833@cindex Contributors 5834@cindex Credits 5835@cindex Authors 5836 5837Most of the parser was hand-crafted by @emph{Andy Vaught}, who is 5838also the initiator of the whole project. Thanks Andy! 5839Most of the interface with GCC was written by @emph{Paul Brook}. 5840 5841The following individuals have contributed code and/or 5842ideas and significant help to the GNU Fortran project 5843(in alphabetical order): 5844 5845@itemize @minus 5846@item Janne Blomqvist 5847@item Steven Bosscher 5848@item Paul Brook 5849@item Tobias Burnus 5850@item Fran@,{c}ois-Xavier Coudert 5851@item Bud Davis 5852@item Jerry DeLisle 5853@item Erik Edelmann 5854@item Bernhard Fischer 5855@item Daniel Franke 5856@item Richard Guenther 5857@item Richard Henderson 5858@item Katherine Holcomb 5859@item Jakub Jelinek 5860@item Niels Kristian Bech Jensen 5861@item Steven Johnson 5862@item Steven G. Kargl 5863@item Thomas Koenig 5864@item Asher Langton 5865@item H. J. Lu 5866@item Toon Moene 5867@item Brooks Moses 5868@item Andrew Pinski 5869@item Tim Prince 5870@item Christopher D. Rickett 5871@item Richard Sandiford 5872@item Tobias Schl@"uter 5873@item Roger Sayle 5874@item Paul Thomas 5875@item Andy Vaught 5876@item Feng Wang 5877@item Janus Weil 5878@item Daniel Kraft 5879@end itemize 5880 5881The following people have contributed bug reports, 5882smaller or larger patches, 5883and much needed feedback and encouragement for the 5884GNU Fortran project: 5885 5886@itemize @minus 5887@item Bill Clodius 5888@item Dominique d'Humi@`eres 5889@item Kate Hedstrom 5890@item Erik Schnetter 5891@item Joost VandeVondele 5892@end itemize 5893 5894Many other individuals have helped debug, 5895test and improve the GNU Fortran compiler over the past few years, 5896and we welcome you to do the same! 5897If you already have done so, 5898and you would like to see your name listed in the 5899list above, please contact us. 5900 5901 5902@node Projects 5903@section Projects 5904 5905@table @emph 5906 5907@item Help build the test suite 5908Solicit more code for donation to the test suite: the more extensive the 5909testsuite, the smaller the risk of breaking things in the future! We can 5910keep code private on request. 5911 5912@item Bug hunting/squishing 5913Find bugs and write more test cases! Test cases are especially very 5914welcome, because it allows us to concentrate on fixing bugs instead of 5915isolating them. Going through the bugzilla database at 5916@url{https://gcc.gnu.org/@/bugzilla/} to reduce testcases posted there and 5917add more information (for example, for which version does the testcase 5918work, for which versions does it fail?) is also very helpful. 5919 5920@end table 5921 5922 5923@node Proposed Extensions 5924@section Proposed Extensions 5925 5926Here's a list of proposed extensions for the GNU Fortran compiler, in no particular 5927order. Most of these are necessary to be fully compatible with 5928existing Fortran compilers, but they are not part of the official 5929J3 Fortran 95 standard. 5930 5931@subsection Compiler extensions: 5932@itemize @bullet 5933@item 5934User-specified alignment rules for structures. 5935 5936@item 5937Automatically extend single precision constants to double. 5938 5939@item 5940Compile code that conserves memory by dynamically allocating common and 5941module storage either on stack or heap. 5942 5943@item 5944Compile flag to generate code for array conformance checking (suggest -CC). 5945 5946@item 5947User control of symbol names (underscores, etc). 5948 5949@item 5950Compile setting for maximum size of stack frame size before spilling 5951parts to static or heap. 5952 5953@item 5954Flag to force local variables into static space. 5955 5956@item 5957Flag to force local variables onto stack. 5958@end itemize 5959 5960 5961@subsection Environment Options 5962@itemize @bullet 5963@item 5964Pluggable library modules for random numbers, linear algebra. 5965LA should use BLAS calling conventions. 5966 5967@item 5968Environment variables controlling actions on arithmetic exceptions like 5969overflow, underflow, precision loss---Generate NaN, abort, default. 5970action. 5971 5972@item 5973Set precision for fp units that support it (i387). 5974 5975@item 5976Variable for setting fp rounding mode. 5977 5978@item 5979Variable to fill uninitialized variables with a user-defined bit 5980pattern. 5981 5982@item 5983Environment variable controlling filename that is opened for that unit 5984number. 5985 5986@item 5987Environment variable to clear/trash memory being freed. 5988 5989@item 5990Environment variable to control tracing of allocations and frees. 5991 5992@item 5993Environment variable to display allocated memory at normal program end. 5994 5995@item 5996Environment variable for filename for * IO-unit. 5997 5998@item 5999Environment variable for temporary file directory. 6000 6001@item 6002Environment variable forcing standard output to be line buffered (Unix). 6003 6004@end itemize 6005 6006 6007@c --------------------------------------------------------------------- 6008@c GNU General Public License 6009@c --------------------------------------------------------------------- 6010 6011@include gpl_v3.texi 6012 6013 6014 6015@c --------------------------------------------------------------------- 6016@c GNU Free Documentation License 6017@c --------------------------------------------------------------------- 6018 6019@include fdl.texi 6020 6021 6022 6023@c --------------------------------------------------------------------- 6024@c Funding Free Software 6025@c --------------------------------------------------------------------- 6026 6027@include funding.texi 6028 6029@c --------------------------------------------------------------------- 6030@c Indices 6031@c --------------------------------------------------------------------- 6032 6033@node Option Index 6034@unnumbered Option Index 6035@command{gfortran}'s command line options are indexed here without any 6036initial @samp{-} or @samp{--}. Where an option has both positive and 6037negative forms (such as -foption and -fno-option), relevant entries in 6038the manual are indexed under the most appropriate form; it may sometimes 6039be useful to look up both forms. 6040@printindex op 6041 6042@node Keyword Index 6043@unnumbered Keyword Index 6044@printindex cp 6045 6046@bye 6047