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