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