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