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