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