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