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