]>
Commit | Line | Data |
---|---|---|
de514255 | 1 | \input texinfo @c -*-texinfo-*- |
6de9cd9a DN |
2 | @c %**start of header |
3 | @setfilename gfortran.info | |
fc1e05d2 | 4 | @set copyrights-gfortran 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 |
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 | ||
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. |
9e0667cd | 185 | * Mixed-Language Programming:: Interoperability with C |
7fc15ba5 BM |
186 | * Extensions:: Language extensions implemented by GNU Fortran. |
187 | * Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran. | |
dcf6c255 | 188 | * Intrinsic Modules:: Intrinsic modules supported by GNU Fortran. |
c8cf50e4 BM |
189 | |
190 | * Contributing:: How you can help. | |
a63dad5b TS |
191 | * Copying:: GNU General Public License says |
192 | how you can copy and share GNU Fortran. | |
193 | * GNU Free Documentation License:: | |
6ccde948 | 194 | How you can copy and share this manual. |
a63dad5b | 195 | * Funding:: How to help assure continued work for free software. |
32864778 DF |
196 | * Option Index:: Index of command line options |
197 | * Keyword Index:: Index of concepts | |
6de9cd9a | 198 | @end menu |
e6b38f67 | 199 | @end ifnottex |
6de9cd9a | 200 | |
6de9cd9a | 201 | @c --------------------------------------------------------------------- |
e6b38f67 | 202 | @c Introduction |
6de9cd9a DN |
203 | @c --------------------------------------------------------------------- |
204 | ||
e6b38f67 BM |
205 | @node Introduction |
206 | @chapter Introduction | |
207 | ||
208 | @c The following duplicates the text on the TexInfo table of contents. | |
209 | @iftex | |
210 | This manual documents the use of @command{gfortran}, the GNU Fortran | |
3994c6b1 | 211 | compiler. You can find in this manual how to invoke @command{gfortran}, |
e6b38f67 BM |
212 | as well as its features and incompatibilities. |
213 | ||
214 | @ifset DEVELOPMENT | |
215 | @emph{Warning:} This document, and the compiler it describes, are still | |
216 | under development. While efforts are made to keep it up-to-date, it | |
217 | might not accurately reflect the status of the most recent GNU Fortran | |
218 | compiler. | |
219 | @end ifset | |
220 | @end iftex | |
6de9cd9a | 221 | |
7fc15ba5 | 222 | The GNU Fortran compiler front end was |
6de9cd9a DN |
223 | designed initially as a free replacement for, |
224 | or alternative to, the unix @command{f95} command; | |
5724da63 | 225 | @command{gfortran} is the command you'll use to invoke the compiler. |
6de9cd9a | 226 | |
e6b38f67 BM |
227 | @menu |
228 | * About GNU Fortran:: What you should know about the GNU Fortran compiler. | |
229 | * GNU Fortran and GCC:: You can compile Fortran, C, or other programs. | |
2b44ab8b | 230 | * Preprocessing and conditional compilation:: The Fortran preprocessor |
e6b38f67 BM |
231 | * GNU Fortran and G77:: Why we chose to start from scratch. |
232 | * Project Status:: Status of GNU Fortran, roadmap, proposed extensions. | |
6ccde948 | 233 | * Standards:: Standards supported by GNU Fortran. |
e6b38f67 BM |
234 | @end menu |
235 | ||
236 | ||
237 | @c --------------------------------------------------------------------- | |
238 | @c About GNU Fortran | |
239 | @c --------------------------------------------------------------------- | |
240 | ||
241 | @node About GNU Fortran | |
242 | @section About GNU Fortran | |
243 | ||
9e0667cd TB |
244 | The GNU Fortran compiler supports the Fortran 77, 90 and 95 standards |
245 | completely, parts of the Fortran 2003 and Fortran 2008 standards, and | |
3994c6b1 | 246 | several vendor extensions. The development goal is to provide the |
9e0667cd | 247 | following features: |
6de9cd9a DN |
248 | |
249 | @itemize @bullet | |
250 | @item | |
251 | Read a user's program, | |
252 | stored in a file and containing instructions written | |
f489fba1 | 253 | in Fortran 77, Fortran 90, Fortran 95, Fortran 2003 or Fortran 2008. |
6de9cd9a DN |
254 | This file contains @dfn{source code}. |
255 | ||
256 | @item | |
257 | Translate the user's program into instructions a computer | |
258 | can carry out more quickly than it takes to translate the | |
259 | instructions in the first | |
260 | place. The result after compilation of a program is | |
261 | @dfn{machine code}, | |
262 | code designed to be efficiently translated and processed | |
263 | by a machine such as your computer. | |
264 | Humans usually aren't as good writing machine code | |
265 | as they are at writing Fortran (or C++, Ada, or Java), | |
aad9c4f4 | 266 | because it is easy to make tiny mistakes writing machine code. |
6de9cd9a DN |
267 | |
268 | @item | |
269 | Provide the user with information about the reasons why | |
270 | the compiler is unable to create a binary from the source code. | |
271 | Usually this will be the case if the source code is flawed. | |
aad9c4f4 | 272 | The Fortran 90 standard requires that the compiler can point out |
6de9cd9a DN |
273 | mistakes to the user. |
274 | An incorrect usage of the language causes an @dfn{error message}. | |
275 | ||
276 | The compiler will also attempt to diagnose cases where the | |
277 | user's program contains a correct usage of the language, | |
278 | but instructs the computer to do something questionable. | |
279 | This kind of diagnostics message is called a @dfn{warning message}. | |
280 | ||
281 | @item | |
282 | Provide optional information about the translation passes | |
283 | from the source code to machine code. | |
284 | This can help a user of the compiler to find the cause of | |
285 | certain bugs which may not be obvious in the source code, | |
286 | but may be more easily found at a lower level compiler output. | |
287 | It also helps developers to find bugs in the compiler itself. | |
288 | ||
289 | @item | |
290 | Provide information in the generated machine code that can | |
291 | make it easier to find bugs in the program (using a debugging tool, | |
292 | called a @dfn{debugger}, such as the GNU Debugger @command{gdb}). | |
293 | ||
294 | @item | |
295 | Locate and gather machine code already generated to | |
296 | perform actions requested by statements in the user's program. | |
297 | This machine code is organized into @dfn{modules} and is located | |
298 | and @dfn{linked} to the user program. | |
299 | @end itemize | |
300 | ||
7fc15ba5 | 301 | The GNU Fortran compiler consists of several components: |
6de9cd9a DN |
302 | |
303 | @itemize @bullet | |
304 | @item | |
305 | A version of the @command{gcc} command | |
306 | (which also might be installed as the system's @command{cc} command) | |
307 | that also understands and accepts Fortran source code. | |
308 | The @command{gcc} command is the @dfn{driver} program for | |
309 | all the languages in the GNU Compiler Collection (GCC); | |
310 | With @command{gcc}, | |
5724da63 | 311 | you can compile the source code of any language for |
6de9cd9a DN |
312 | which a front end is available in GCC. |
313 | ||
314 | @item | |
315 | The @command{gfortran} command itself, | |
316 | which also might be installed as the | |
317 | system's @command{f95} command. | |
318 | @command{gfortran} is just another driver program, | |
7fc15ba5 | 319 | but specifically for the Fortran compiler only. |
6de9cd9a DN |
320 | The difference with @command{gcc} is that @command{gfortran} |
321 | will automatically link the correct libraries to your program. | |
322 | ||
323 | @item | |
324 | A collection of run-time libraries. | |
5724da63 | 325 | These libraries contain the machine code needed to support |
6de9cd9a DN |
326 | capabilities of the Fortran language that are not directly |
327 | provided by the machine code generated by the | |
328 | @command{gfortran} compilation phase, | |
329 | such as intrinsic functions and subroutines, | |
330 | and routines for interaction with files and the operating system. | |
331 | @c and mechanisms to spawn, | |
332 | @c unleash and pause threads in parallelized code. | |
333 | ||
334 | @item | |
335 | The Fortran compiler itself, (@command{f951}). | |
7fc15ba5 | 336 | This is the GNU Fortran parser and code generator, |
6de9cd9a DN |
337 | linked to and interfaced with the GCC backend library. |
338 | @command{f951} ``translates'' the source code to | |
339 | assembler code. You would typically not use this | |
340 | program directly; | |
341 | instead, the @command{gcc} or @command{gfortran} driver | |
342 | programs will call it for you. | |
343 | @end itemize | |
344 | ||
345 | ||
6de9cd9a | 346 | @c --------------------------------------------------------------------- |
7fc15ba5 | 347 | @c GNU Fortran and GCC |
6de9cd9a DN |
348 | @c --------------------------------------------------------------------- |
349 | ||
7fc15ba5 | 350 | @node GNU Fortran and GCC |
e6b38f67 | 351 | @section GNU Fortran and GCC |
6de9cd9a | 352 | @cindex GNU Compiler Collection |
de43c613 BM |
353 | @cindex GCC |
354 | ||
355 | GNU Fortran is a part of GCC, the @dfn{GNU Compiler Collection}. GCC | |
356 | consists of a collection of front ends for various languages, which | |
357 | translate the source code into a language-independent form called | |
358 | @dfn{GENERIC}. This is then processed by a common middle end which | |
359 | provides optimization, and then passed to one of a collection of back | |
360 | ends which generate code for different computer architectures and | |
361 | operating systems. | |
362 | ||
363 | Functionally, this is implemented with a driver program (@command{gcc}) | |
364 | which provides the command-line interface for the compiler. It calls | |
365 | the relevant compiler front-end program (e.g., @command{f951} for | |
366 | Fortran) for each file in the source code, and then calls the assembler | |
3994c6b1 | 367 | and linker as appropriate to produce the compiled output. In a copy of |
de43c613 | 368 | GCC which has been compiled with Fortran language support enabled, |
1200489c | 369 | @command{gcc} will recognize files with @file{.f}, @file{.for}, @file{.ftn}, |
f489fba1 | 370 | @file{.f90}, @file{.f95}, @file{.f03} and @file{.f08} extensions as |
3994c6b1 | 371 | Fortran source code, and compile it accordingly. A @command{gfortran} |
f489fba1 FXC |
372 | driver program is also provided, which is identical to @command{gcc} |
373 | except that it automatically links the Fortran runtime libraries into the | |
374 | compiled program. | |
de43c613 | 375 | |
48d5fab4 JD |
376 | Source files with @file{.f}, @file{.for}, @file{.fpp}, @file{.ftn}, @file{.F}, |
377 | @file{.FOR}, @file{.FPP}, and @file{.FTN} extensions are treated as fixed form. | |
f489fba1 FXC |
378 | Source files with @file{.f90}, @file{.f95}, @file{.f03}, @file{.f08}, |
379 | @file{.F90}, @file{.F95}, @file{.F03} and @file{.F08} extensions are | |
380 | treated as free form. The capitalized versions of either form are run | |
3994c6b1 | 381 | through preprocessing. Source files with the lower case @file{.fpp} |
f489fba1 | 382 | extension are also run through preprocessing. |
48d5fab4 | 383 | |
de43c613 BM |
384 | This manual specifically documents the Fortran front end, which handles |
385 | the programming language's syntax and semantics. The aspects of GCC | |
386 | which relate to the optimization passes and the back-end code generation | |
387 | are documented in the GCC manual; see | |
388 | @ref{Top,,Introduction,gcc,Using the GNU Compiler Collection (GCC)}. | |
389 | The two manuals together provide a complete reference for the GNU | |
390 | Fortran compiler. | |
6de9cd9a DN |
391 | |
392 | ||
2b44ab8b TB |
393 | @c --------------------------------------------------------------------- |
394 | @c Preprocessing and conditional compilation | |
395 | @c --------------------------------------------------------------------- | |
396 | ||
397 | @node Preprocessing and conditional compilation | |
398 | @section Preprocessing and conditional compilation | |
399 | @cindex CPP | |
400 | @cindex FPP | |
401 | @cindex Conditional compilation | |
402 | @cindex Preprocessing | |
f34cf28d | 403 | @cindex preprocessor, include file handling |
2b44ab8b | 404 | |
48d5fab4 JD |
405 | Many Fortran compilers including GNU Fortran allow passing the source code |
406 | through a C preprocessor (CPP; sometimes also called the Fortran preprocessor, | |
3994c6b1 TB |
407 | FPP) to allow for conditional compilation. In the case of GNU Fortran, |
408 | this is the GNU C Preprocessor in the traditional mode. On systems with | |
2b44ab8b | 409 | case-preserving file names, the preprocessor is automatically invoked if the |
3994c6b1 TB |
410 | filename extension is @file{.F}, @file{.FOR}, @file{.FTN}, @file{.fpp}, |
411 | @file{.FPP}, @file{.F90}, @file{.F95}, @file{.F03} or @file{.F08}. To manually | |
670637ee DF |
412 | invoke the preprocessor on any file, use @option{-cpp}, to disable |
413 | preprocessing on files where the preprocessor is run automatically, use | |
414 | @option{-nocpp}. | |
2b44ab8b | 415 | |
f34cf28d | 416 | If a preprocessed file includes another file with the Fortran @code{INCLUDE} |
3994c6b1 | 417 | statement, the included file is not preprocessed. To preprocess included |
f34cf28d DF |
418 | files, use the equivalent preprocessor statement @code{#include}. |
419 | ||
420 | If GNU Fortran invokes the preprocessor, @code{__GFORTRAN__} | |
2b44ab8b TB |
421 | is defined and @code{__GNUC__}, @code{__GNUC_MINOR__} and |
422 | @code{__GNUC_PATCHLEVEL__} can be used to determine the version of the | |
3994c6b1 | 423 | compiler. See @ref{Top,,Overview,cpp,The C Preprocessor} for details. |
2b44ab8b TB |
424 | |
425 | While CPP is the de-facto standard for preprocessing Fortran code, | |
426 | Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines | |
427 | Conditional Compilation, which is not widely used and not directly | |
3994c6b1 | 428 | supported by the GNU Fortran compiler. You can use the program coco |
f39168b3 | 429 | to preprocess such files (@uref{http://www.daniellnagle.com/coco.html}). |
2b44ab8b TB |
430 | |
431 | ||
6de9cd9a | 432 | @c --------------------------------------------------------------------- |
7fc15ba5 | 433 | @c GNU Fortran and G77 |
6de9cd9a DN |
434 | @c --------------------------------------------------------------------- |
435 | ||
7fc15ba5 | 436 | @node GNU Fortran and G77 |
e6b38f67 | 437 | @section GNU Fortran and G77 |
6de9cd9a | 438 | @cindex Fortran 77 |
e739dfac | 439 | @cindex @command{g77} |
6de9cd9a | 440 | |
e739dfac DF |
441 | The GNU Fortran compiler is the successor to @command{g77}, the Fortran |
442 | 77 front end included in GCC prior to version 4. It is an entirely new | |
443 | program that has been designed to provide Fortran 95 support and | |
444 | extensibility for future Fortran language standards, as well as providing | |
445 | backwards compatibility for Fortran 77 and nearly all of the GNU language | |
446 | extensions supported by @command{g77}. | |
6de9cd9a | 447 | |
6de9cd9a | 448 | |
6de9cd9a DN |
449 | @c --------------------------------------------------------------------- |
450 | @c Project Status | |
451 | @c --------------------------------------------------------------------- | |
452 | ||
453 | @node Project Status | |
e6b38f67 | 454 | @section Project Status |
6de9cd9a DN |
455 | |
456 | @quotation | |
7fc15ba5 | 457 | As soon as @command{gfortran} can parse all of the statements correctly, |
6de9cd9a DN |
458 | it will be in the ``larva'' state. |
459 | When we generate code, the ``puppa'' state. | |
7fc15ba5 | 460 | When @command{gfortran} is done, |
6de9cd9a DN |
461 | we'll see if it will be a beautiful butterfly, |
462 | or just a big bug.... | |
463 | ||
464 | --Andy Vaught, April 2000 | |
465 | @end quotation | |
466 | ||
467 | The start of the GNU Fortran 95 project was announced on | |
468 | the GCC homepage in March 18, 2000 | |
469 | (even though Andy had already been working on it for a while, | |
5724da63 | 470 | of course). |
6de9cd9a | 471 | |
cf822c04 BM |
472 | The GNU Fortran compiler is able to compile nearly all |
473 | standard-compliant Fortran 95, Fortran 90, and Fortran 77 programs, | |
474 | including a number of standard and non-standard extensions, and can be | |
475 | used on real-world programs. In particular, the supported extensions | |
f489fba1 | 476 | include OpenMP, Cray-style pointers, and several Fortran 2003 and Fortran |
3994c6b1 TB |
477 | 2008 features, including TR 15581. However, it is still under |
478 | development and has a few remaining rough edges. | |
cf822c04 BM |
479 | |
480 | At present, the GNU Fortran compiler passes the | |
481 | @uref{http://www.fortran-2000.com/ArnaudRecipes/fcvs21_f95.html, | |
482 | NIST Fortran 77 Test Suite}, and produces acceptable results on the | |
483 | @uref{http://www.netlib.org/lapack/faq.html#1.21, LAPACK Test Suite}. | |
484 | It also provides respectable performance on | |
485 | the @uref{http://www.polyhedron.com/pb05.html, Polyhedron Fortran | |
486 | compiler benchmarks} and the | |
487 | @uref{http://www.llnl.gov/asci_benchmarks/asci/limited/lfk/README.html, | |
488 | Livermore Fortran Kernels test}. It has been used to compile a number of | |
489 | large real-world programs, including | |
490 | @uref{http://mysite.verizon.net/serveall/moene.pdf, the HIRLAM | |
491 | weather-forecasting code} and | |
492 | @uref{http://www.theochem.uwa.edu.au/tonto/, the Tonto quantum | |
3994c6b1 | 493 | chemistry package}; see @url{http://gcc.gnu.org/@/wiki/@/GfortranApps} for an |
26d29061 | 494 | extended list. |
cf822c04 BM |
495 | |
496 | Among other things, the GNU Fortran compiler is intended as a replacement | |
497 | for G77. At this point, nearly all programs that could be compiled with | |
498 | G77 can be compiled with GNU Fortran, although there are a few minor known | |
499 | regressions. | |
500 | ||
501 | The primary work remaining to be done on GNU Fortran falls into three | |
502 | categories: bug fixing (primarily regarding the treatment of invalid code | |
503 | and providing useful error messages), improving the compiler optimizations | |
504 | and the performance of compiled code, and extending the compiler to support | |
9e0667cd | 505 | future standards---in particular, Fortran 2003 and Fortran 2008. |
cf822c04 | 506 | |
6de9cd9a | 507 | |
c8cf50e4 BM |
508 | @c --------------------------------------------------------------------- |
509 | @c Standards | |
510 | @c --------------------------------------------------------------------- | |
6de9cd9a | 511 | |
c8cf50e4 | 512 | @node Standards |
e6b38f67 | 513 | @section Standards |
c8cf50e4 | 514 | @cindex Standards |
6de9cd9a | 515 | |
9e0667cd TB |
516 | @menu |
517 | * Varying Length Character Strings:: | |
518 | @end menu | |
519 | ||
c8cf50e4 BM |
520 | The GNU Fortran compiler implements |
521 | ISO/IEC 1539:1997 (Fortran 95). As such, it can also compile essentially all | |
522 | standard-compliant Fortran 90 and Fortran 77 programs. It also supports | |
3994c6b1 | 523 | the ISO/IEC TR-15581 enhancements to allocatable arrays. |
6de9cd9a | 524 | |
f489fba1 | 525 | In the future, the GNU Fortran compiler will also support ISO/IEC |
3994c6b1 TB |
526 | 1539-1:2004 (Fortran 2003), ISO/IEC 1539-1:2010 (Fortran 2008) and |
527 | future Fortran standards. Partial support of the Fortran 2003 and | |
528 | Fortran 2008 standard is already provided; the current status of the | |
529 | support is reported in the @ref{Fortran 2003 status} and | |
530 | @ref{Fortran 2008 status} sections of the documentation. | |
6de9cd9a | 531 | |
9e0667cd | 532 | Additionally, the GNU Fortran compilers supports the OpenMP specification |
3994c6b1 | 533 | (version 3.0, @url{http://openmp.org/@/wp/@/openmp-specifications/}). |
9e0667cd TB |
534 | |
535 | @node Varying Length Character Strings | |
536 | @subsection Varying Length Character Strings | |
537 | @cindex Varying length character strings | |
538 | @cindex Varying length strings | |
539 | @cindex strings, varying length | |
540 | ||
541 | The Fortran 95 standard specifies in Part 2 (ISO/IEC 1539-2:2000) | |
3994c6b1 | 542 | varying length character strings. While GNU Fortran currently does not |
9e0667cd | 543 | support such strings directly, there exist two Fortran implementations |
3994c6b1 | 544 | for them, which work with GNU Fortran. They can be found at |
9e0667cd TB |
545 | @uref{http://www.fortran.com/@/iso_varying_string.f95} and at |
546 | @uref{ftp://ftp.nag.co.uk/@/sc22wg5/@/ISO_VARYING_STRING/}. | |
547 | ||
548 | ||
6de9cd9a | 549 | |
c8cf50e4 | 550 | @c ===================================================================== |
e6b38f67 | 551 | @c PART I: INVOCATION REFERENCE |
c8cf50e4 | 552 | @c ===================================================================== |
6de9cd9a | 553 | |
c8cf50e4 | 554 | @tex |
e6b38f67 | 555 | \part{I}{Invoking GNU Fortran} |
c8cf50e4 | 556 | @end tex |
6de9cd9a | 557 | |
c8cf50e4 BM |
558 | @c --------------------------------------------------------------------- |
559 | @c Compiler Options | |
560 | @c --------------------------------------------------------------------- | |
6de9cd9a | 561 | |
c8cf50e4 | 562 | @include invoke.texi |
6de9cd9a | 563 | |
cf822c04 BM |
564 | |
565 | @c --------------------------------------------------------------------- | |
566 | @c Runtime | |
567 | @c --------------------------------------------------------------------- | |
568 | ||
eaa90d25 TK |
569 | @node Runtime |
570 | @chapter Runtime: Influencing runtime behavior with environment variables | |
e739dfac | 571 | @cindex environment variable |
eaa90d25 | 572 | |
b82feea5 | 573 | The behavior of the @command{gfortran} can be influenced by |
eaa90d25 | 574 | environment variables. |
f5dc42bb TK |
575 | |
576 | Malformed environment variables are silently ignored. | |
577 | ||
eaa90d25 | 578 | @menu |
f5dc42bb TK |
579 | * GFORTRAN_STDIN_UNIT:: Unit number for standard input |
580 | * GFORTRAN_STDOUT_UNIT:: Unit number for standard output | |
581 | * GFORTRAN_STDERR_UNIT:: Unit number for standard error | |
f5dc42bb | 582 | * GFORTRAN_TMPDIR:: Directory for scratch files |
6e34d7b8 | 583 | * GFORTRAN_UNBUFFERED_ALL:: Don't buffer I/O for all units. |
f41899f6 | 584 | * GFORTRAN_UNBUFFERED_PRECONNECTED:: Don't buffer I/O for preconnected units. |
f5dc42bb TK |
585 | * GFORTRAN_SHOW_LOCUS:: Show location for runtime errors |
586 | * GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted | |
587 | * GFORTRAN_DEFAULT_RECL:: Default record length for new files | |
588 | * GFORTRAN_LIST_SEPARATOR:: Separator for list output | |
eaa90d25 | 589 | * GFORTRAN_CONVERT_UNIT:: Set endianness for unformatted I/O |
a0cb58b2 | 590 | * GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors |
eaa90d25 TK |
591 | @end menu |
592 | ||
f5dc42bb TK |
593 | @node GFORTRAN_STDIN_UNIT |
594 | @section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input | |
595 | ||
596 | This environment variable can be used to select the unit number | |
597 | preconnected to standard input. This must be a positive integer. | |
598 | The default value is 5. | |
599 | ||
600 | @node GFORTRAN_STDOUT_UNIT | |
601 | @section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output | |
602 | ||
603 | This environment variable can be used to select the unit number | |
604 | preconnected to standard output. This must be a positive integer. | |
605 | The default value is 6. | |
606 | ||
607 | @node GFORTRAN_STDERR_UNIT | |
608 | @section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error | |
609 | ||
610 | This environment variable can be used to select the unit number | |
611 | preconnected to standard error. This must be a positive integer. | |
612 | The default value is 0. | |
613 | ||
f5dc42bb TK |
614 | @node GFORTRAN_TMPDIR |
615 | @section @env{GFORTRAN_TMPDIR}---Directory for scratch files | |
616 | ||
617 | This environment variable controls where scratch files are | |
618 | created. If this environment variable is missing, | |
0e9496cc JD |
619 | GNU Fortran searches for the environment variable @env{TMP}, then @env{TEMP}. |
620 | If these are missing, the default is @file{/tmp}. | |
f5dc42bb TK |
621 | |
622 | @node GFORTRAN_UNBUFFERED_ALL | |
6e34d7b8 | 623 | @section @env{GFORTRAN_UNBUFFERED_ALL}---Don't buffer I/O on all units |
f5dc42bb | 624 | |
6e34d7b8 JB |
625 | This environment variable controls whether all I/O is unbuffered. If |
626 | the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is | |
3994c6b1 | 627 | unbuffered. This will slow down small sequential reads and writes. If |
6e34d7b8 JB |
628 | the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. |
629 | This is the default. | |
f5dc42bb | 630 | |
f41899f6 | 631 | @node GFORTRAN_UNBUFFERED_PRECONNECTED |
49309826 | 632 | @section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Don't buffer I/O on preconnected units |
f41899f6 JD |
633 | |
634 | The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls | |
24219f12 | 635 | whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) is unbuffered. If |
3994c6b1 | 636 | the first letter is @samp{y}, @samp{Y} or @samp{1}, I/O is unbuffered. This |
f41899f6 JD |
637 | will slow down small sequential reads and writes. If the first letter |
638 | is @samp{n}, @samp{N} or @samp{0}, I/O is buffered. This is the default. | |
639 | ||
f5dc42bb TK |
640 | @node GFORTRAN_SHOW_LOCUS |
641 | @section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors | |
642 | ||
643 | If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and | |
644 | line numbers for runtime errors are printed. If the first letter is | |
645 | @samp{n}, @samp{N} or @samp{0}, don't print filename and line numbers | |
3994c6b1 | 646 | for runtime errors. The default is to print the location. |
f5dc42bb TK |
647 | |
648 | @node GFORTRAN_OPTIONAL_PLUS | |
649 | @section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted | |
650 | ||
651 | If the first letter is @samp{y}, @samp{Y} or @samp{1}, | |
652 | a plus sign is printed | |
b82feea5 | 653 | where permitted by the Fortran standard. If the first letter |
f5dc42bb | 654 | is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed |
3994c6b1 | 655 | in most cases. Default is not to print plus signs. |
f5dc42bb TK |
656 | |
657 | @node GFORTRAN_DEFAULT_RECL | |
658 | @section @env{GFORTRAN_DEFAULT_RECL}---Default record length for new files | |
659 | ||
11de78ff BM |
660 | This environment variable specifies the default record length, in |
661 | bytes, for files which are opened without a @code{RECL} tag in the | |
662 | @code{OPEN} statement. This must be a positive integer. The | |
663 | default value is 1073741824 bytes (1 GB). | |
f5dc42bb TK |
664 | |
665 | @node GFORTRAN_LIST_SEPARATOR | |
666 | @section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output | |
667 | ||
668 | This environment variable specifies the separator when writing | |
669 | list-directed output. It may contain any number of spaces and | |
670 | at most one comma. If you specify this on the command line, | |
671 | be sure to quote spaces, as in | |
672 | @smallexample | |
673 | $ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out | |
674 | @end smallexample | |
40746dcc | 675 | when @command{a.out} is the compiled Fortran program that you want to run. |
f5dc42bb TK |
676 | Default is a single space. |
677 | ||
eaa90d25 | 678 | @node GFORTRAN_CONVERT_UNIT |
f5dc42bb | 679 | @section @env{GFORTRAN_CONVERT_UNIT}---Set endianness for unformatted I/O |
eaa90d25 | 680 | |
f5dc42bb | 681 | By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible |
eaa90d25 | 682 | to change the representation of data for unformatted files. |
f5dc42bb | 683 | The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable is: |
eaa90d25 | 684 | @smallexample |
1941551a | 685 | GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ; |
eaa90d25 TK |
686 | mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ; |
687 | exception: mode ':' unit_list | unit_list ; | |
688 | unit_list: unit_spec | unit_list unit_spec ; | |
689 | unit_spec: INTEGER | INTEGER '-' INTEGER ; | |
690 | @end smallexample | |
691 | The variable consists of an optional default mode, followed by | |
692 | a list of optional exceptions, which are separated by semicolons | |
693 | from the preceding default and each other. Each exception consists | |
694 | of a format and a comma-separated list of units. Valid values for | |
695 | the modes are the same as for the @code{CONVERT} specifier: | |
696 | ||
697 | @itemize @w{} | |
698 | @item @code{NATIVE} Use the native format. This is the default. | |
699 | @item @code{SWAP} Swap between little- and big-endian. | |
700 | @item @code{LITTLE_ENDIAN} Use the little-endian format | |
6ccde948 | 701 | for unformatted files. |
eaa90d25 TK |
702 | @item @code{BIG_ENDIAN} Use the big-endian format for unformatted files. |
703 | @end itemize | |
704 | A missing mode for an exception is taken to mean @code{BIG_ENDIAN}. | |
40746dcc | 705 | Examples of values for @env{GFORTRAN_CONVERT_UNIT} are: |
eaa90d25 TK |
706 | @itemize @w{} |
707 | @item @code{'big_endian'} Do all unformatted I/O in big_endian mode. | |
708 | @item @code{'little_endian;native:10-20,25'} Do all unformatted I/O | |
709 | in little_endian mode, except for units 10 to 20 and 25, which are in | |
710 | native format. | |
711 | @item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native. | |
6de9cd9a DN |
712 | @end itemize |
713 | ||
eaa90d25 | 714 | Setting the environment variables should be done on the command |
40746dcc BM |
715 | line or via the @command{export} |
716 | command for @command{sh}-compatible shells and via @command{setenv} | |
717 | for @command{csh}-compatible shells. | |
eaa90d25 | 718 | |
40746dcc | 719 | Example for @command{sh}: |
eaa90d25 TK |
720 | @smallexample |
721 | $ gfortran foo.f90 | |
722 | $ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out | |
723 | @end smallexample | |
724 | ||
40746dcc | 725 | Example code for @command{csh}: |
eaa90d25 TK |
726 | @smallexample |
727 | % gfortran foo.f90 | |
728 | % setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20' | |
729 | % ./a.out | |
730 | @end smallexample | |
731 | ||
732 | Using anything but the native representation for unformatted data | |
733 | carries a significant speed overhead. If speed in this area matters | |
734 | to you, it is best if you use this only for data that needs to be | |
735 | portable. | |
736 | ||
737 | @xref{CONVERT specifier}, for an alternative way to specify the | |
738 | data representation for unformatted files. @xref{Runtime Options}, for | |
739 | setting a default data representation for the whole program. The | |
40746dcc | 740 | @code{CONVERT} specifier overrides the @option{-fconvert} compile options. |
eaa90d25 | 741 | |
1941551a TB |
742 | @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT |
743 | environment variable will override the CONVERT specifier in the | |
744 | open statement}. This is to give control over data formats to | |
745 | users who do not have the source code of their program available. | |
746 | ||
a0cb58b2 TB |
747 | @node GFORTRAN_ERROR_BACKTRACE |
748 | @section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors | |
749 | ||
de8bd142 JB |
750 | If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to @samp{y}, |
751 | @samp{Y} or @samp{1} (only the first letter is relevant) then a | |
752 | backtrace is printed when a serious run-time error occurs. To disable | |
753 | the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}. | |
754 | Default is to print a backtrace unless the @option{-fno-backtrace} | |
755 | compile option was used. | |
c8cf50e4 BM |
756 | |
757 | @c ===================================================================== | |
e6b38f67 | 758 | @c PART II: LANGUAGE REFERENCE |
c8cf50e4 BM |
759 | @c ===================================================================== |
760 | ||
761 | @tex | |
e6b38f67 | 762 | \part{II}{Language Reference} |
c8cf50e4 BM |
763 | @end tex |
764 | ||
765 | @c --------------------------------------------------------------------- | |
f489fba1 | 766 | @c Fortran 2003 and 2008 Status |
c8cf50e4 BM |
767 | @c --------------------------------------------------------------------- |
768 | ||
f489fba1 FXC |
769 | @node Fortran 2003 and 2008 status |
770 | @chapter Fortran 2003 and 2008 Status | |
771 | ||
772 | @menu | |
773 | * Fortran 2003 status:: | |
774 | * Fortran 2008 status:: | |
775 | @end menu | |
776 | ||
c8cf50e4 | 777 | @node Fortran 2003 status |
f489fba1 | 778 | @section Fortran 2003 status |
c8cf50e4 | 779 | |
9e0667cd | 780 | GNU Fortran supports several Fortran 2003 features; an incomplete |
26ef2b42 DK |
781 | list can be found below. See also the |
782 | @uref{http://gcc.gnu.org/wiki/Fortran2003, wiki page} about Fortran 2003. | |
c8cf50e4 BM |
783 | |
784 | @itemize | |
fc1e05d2 TB |
785 | @item Procedure pointers including procedure-pointer components with |
786 | @code{PASS} attribute. | |
c8cf50e4 | 787 | |
fc1e05d2 TB |
788 | @item Procedures which are bound to a derived type (type-bound procedures) |
789 | including @code{PASS}, @code{PROCEDURE} and @code{GENERIC}, and | |
790 | operators bound to a type. | |
791 | ||
dd5a833e | 792 | @item Abstract interfaces and type extension with the possibility to |
fc1e05d2 TB |
793 | override type-bound procedures or to have deferred binding. |
794 | ||
795 | @item Polymorphic entities (``@code{CLASS}'') for derived types -- including | |
796 | @code{SAME_TYPE_AS}, @code{EXTENDS_TYPE_OF} and @code{SELECT TYPE}. | |
797 | Note that the support for array-valued polymorphic entities is incomplete | |
798 | and unlimited polymophism is currently not supported. | |
799 | ||
800 | @item The @code{ASSOCIATE} construct. | |
801 | ||
802 | @item Interoperability with C including enumerations, | |
803 | ||
804 | @item In structure constructors the components with default values may be | |
805 | omitted. | |
806 | ||
807 | @item Extensions to the @code{ALLOCATE} statement, allowing for a | |
808 | type-specification with type parameter and for allocation and initialization | |
809 | from a @code{SOURCE=} expression; @code{ALLOCATE} and @code{DEALLOCATE} | |
810 | optionally return an error message string via @code{ERRMSG=}. | |
811 | ||
8d51f26f | 812 | @item Reallocation on assignment: If an intrinsic assignment is |
fc1e05d2 | 813 | used, an allocatable variable on the left-hand side is automatically allocated |
8d51f26f PT |
814 | (if unallocated) or reallocated (if the shape is different). Currently, scalar |
815 | deferred character length left-hand sides are correctly handled but arrays | |
816 | are not yet fully implemented. | |
fc1e05d2 TB |
817 | |
818 | @item Transferring of allocations via @code{MOVE_ALLOC}. | |
819 | ||
820 | @item The @code{PRIVATE} and @code{PUBLIC} attributes may be given individually | |
821 | to derived-type components. | |
822 | ||
823 | @item In pointer assignments, the lower bound may be specified and | |
824 | the remapping of elements is supported. | |
825 | ||
826 | @item For pointers an @code{INTENT} may be specified which affect the | |
827 | association status not the value of the pointer target. | |
828 | ||
829 | @item Intrinsics @code{command_argument_count}, @code{get_command}, | |
830 | @code{get_command_argument}, and @code{get_environment_variable}. | |
831 | ||
832 | @item Support for unicode characters (ISO 10646) and UTF-8, including | |
833 | the @code{SELECTED_CHAR_KIND} and @code{NEW_LINE} intrinsic functions. | |
834 | ||
835 | @item Support for binary, octal and hexadecimal (BOZ) constants in the | |
836 | intrinsic functions @code{INT}, @code{REAL}, @code{CMPLX} and @code{DBLE}. | |
837 | ||
5582f599 TB |
838 | @item Support for namelist variables with allocatable and pointer |
839 | attribute and nonconstant length type parameter. | |
840 | ||
fc1e05d2 | 841 | @item |
e739dfac | 842 | @cindex array, constructors |
c8cf50e4 | 843 | @cindex @code{[...]} |
3994c6b1 | 844 | Array constructors using square brackets. That is, @code{[...]} rather |
26ef2b42 DK |
845 | than @code{(/.../)}. Type-specification for array constructors like |
846 | @code{(/ some-type :: ... /)}. | |
c8cf50e4 | 847 | |
fc1e05d2 TB |
848 | @item Extensions to the specification and initialization expressions, |
849 | including the support for intrinsics with real and complex arguments. | |
850 | ||
851 | @item Support for the asynchronous input/output syntax; however, the | |
852 | data transfer is currently always synchronously performed. | |
853 | ||
c8cf50e4 BM |
854 | @item |
855 | @cindex @code{FLUSH} statement | |
e739dfac | 856 | @cindex statement, @code{FLUSH} |
c8cf50e4 BM |
857 | @code{FLUSH} statement. |
858 | ||
859 | @item | |
860 | @cindex @code{IOMSG=} specifier | |
861 | @code{IOMSG=} specifier for I/O statements. | |
862 | ||
863 | @item | |
864 | @cindex @code{ENUM} statement | |
865 | @cindex @code{ENUMERATOR} statement | |
e739dfac DF |
866 | @cindex statement, @code{ENUM} |
867 | @cindex statement, @code{ENUMERATOR} | |
32864778 | 868 | @opindex @code{fshort-enums} |
c8cf50e4 BM |
869 | Support for the declaration of enumeration constants via the |
870 | @code{ENUM} and @code{ENUMERATOR} statements. Interoperability with | |
871 | @command{gcc} is guaranteed also for the case where the | |
872 | @command{-fshort-enums} command line option is given. | |
873 | ||
874 | @item | |
875 | @cindex TR 15581 | |
876 | TR 15581: | |
877 | @itemize | |
878 | @item | |
879 | @cindex @code{ALLOCATABLE} dummy arguments | |
880 | @code{ALLOCATABLE} dummy arguments. | |
881 | @item | |
882 | @cindex @code{ALLOCATABLE} function results | |
883 | @code{ALLOCATABLE} function results | |
884 | @item | |
885 | @cindex @code{ALLOCATABLE} components of derived types | |
886 | @code{ALLOCATABLE} components of derived types | |
887 | @end itemize | |
888 | ||
889 | @item | |
890 | @cindex @code{STREAM} I/O | |
891 | @cindex @code{ACCESS='STREAM'} I/O | |
892 | The @code{OPEN} statement supports the @code{ACCESS='STREAM'} specifier, | |
893 | allowing I/O without any record structure. | |
894 | ||
895 | @item | |
896 | Namelist input/output for internal files. | |
897 | ||
fc1e05d2 TB |
898 | @item Further I/O extensions: Rounding during formatted output, using of |
899 | a decimal comma instead of a decimal point, setting whether a plus sign | |
900 | should appear for positive numbers. | |
901 | ||
c8cf50e4 | 902 | @item |
e739dfac DF |
903 | @cindex @code{PROTECTED} statement |
904 | @cindex statement, @code{PROTECTED} | |
c8cf50e4 BM |
905 | The @code{PROTECTED} statement and attribute. |
906 | ||
907 | @item | |
e739dfac DF |
908 | @cindex @code{VALUE} statement |
909 | @cindex statement, @code{VALUE} | |
c8cf50e4 BM |
910 | The @code{VALUE} statement and attribute. |
911 | ||
912 | @item | |
e739dfac DF |
913 | @cindex @code{VOLATILE} statement |
914 | @cindex statement, @code{VOLATILE} | |
c8cf50e4 BM |
915 | The @code{VOLATILE} statement and attribute. |
916 | ||
917 | @item | |
e739dfac DF |
918 | @cindex @code{IMPORT} statement |
919 | @cindex statement, @code{IMPORT} | |
c8cf50e4 BM |
920 | The @code{IMPORT} statement, allowing to import |
921 | host-associated derived types. | |
922 | ||
fc1e05d2 TB |
923 | @item The intrinsic modules @code{ISO_FORTRAN_ENVIRONMENT} is supported, |
924 | which contains parameters of the I/O units, storage sizes. Additionally, | |
925 | procedures for C interoperability are available in the @code{ISO_C_BINDING} | |
926 | module. | |
927 | ||
c8cf50e4 | 928 | @item |
e739dfac DF |
929 | @cindex @code{USE, INTRINSIC} statement |
930 | @cindex statement, @code{USE, INTRINSIC} | |
931 | @cindex @code{ISO_FORTRAN_ENV} statement | |
932 | @cindex statement, @code{ISO_FORTRAN_ENV} | |
c8cf50e4 BM |
933 | @code{USE} statement with @code{INTRINSIC} and @code{NON_INTRINSIC} |
934 | attribute; supported intrinsic modules: @code{ISO_FORTRAN_ENV}, | |
fc1e05d2 | 935 | @code{ISO_C_BINDING}, @code{OMP_LIB} and @code{OMP_LIB_KINDS}. |
c8cf50e4 | 936 | |
56bedf42 TB |
937 | @item |
938 | Renaming of operators in the @code{USE} statement. | |
939 | ||
c8cf50e4 BM |
940 | @end itemize |
941 | ||
942 | ||
f489fba1 FXC |
943 | @node Fortran 2008 status |
944 | @section Fortran 2008 status | |
945 | ||
3994c6b1 TB |
946 | The latest version of the Fortran standard is ISO/IEC 1539-1:2010, informally |
947 | known as Fortran 2008. The official version is available from International | |
948 | Organization for Standardization (ISO) or its national member organizations. | |
949 | The the final draft (FDIS) can be downloaded free of charge from | |
950 | @url{http://www.nag.co.uk/@/sc22wg5/@/links.html}. Fortran is developed by the | |
951 | Working Group 5 of Sub-Committee 22 of the Joint Technical Committee 1 of the | |
952 | International Organization for Standardization and the International | |
953 | Electrotechnical Commission (IEC). This group is known as | |
954 | @uref{http://www.nag.co.uk/sc22wg5/, WG5}. | |
955 | ||
956 | The GNU Fortran supports several of the new features of Fortran 2008; the | |
957 | @uref{http://gcc.gnu.org/wiki/Fortran2008Status, wiki} has some information | |
958 | about the current Fortran 2008 implementation status. In particular, the | |
959 | following is implemented. | |
960 | ||
961 | @itemize | |
962 | @item The @option{-std=f2008} option and support for the file extensions | |
963 | @file{.f08} and @file{.F08}. | |
964 | ||
965 | @item The @code{OPEN} statement now supports the @code{NEWUNIT=} option, | |
966 | which returns a unique file unit, thus preventing inadvertent use of the | |
967 | same unit in different parts of the program. | |
968 | ||
969 | @item The @code{g0} format descriptor and unlimited format items. | |
970 | ||
971 | @item The mathematical intrinsics @code{ASINH}, @code{ACOSH}, @code{ATANH}, | |
972 | @code{ERF}, @code{ERFC}, @code{GAMMA}, @code{LOG_GAMMA}, @code{BESSEL_J0}, | |
973 | @code{BESSEL_J1}, @code{BESSEL_JN}, @code{BESSEL_Y0}, @code{BESSEL_Y1}, | |
974 | @code{BESSEL_YN}, @code{HYPOT}, @code{NORM2}, and @code{ERFC_SCALED}. | |
975 | ||
976 | @item Using complex arguments with @code{TAN}, @code{SINH}, @code{COSH}, | |
977 | @code{TANH}, @code{ASIN}, @code{ACOS}, and @code{ATAN} is now possible; | |
978 | @code{ATAN}(@var{Y},@var{X}) is now an alias for @code{ATAN2}(@var{Y},@var{X}). | |
979 | ||
980 | @item Support of the @code{PARITY} intrinsic functions. | |
981 | ||
982 | @item The following bit intrinsics: @code{LEADZ} and @code{TRAILZ} for | |
983 | counting the number of leading and trailing zero bits, @code{POPCNT} and | |
984 | @code{POPPAR} for counting the number of one bits and returning the parity; | |
985 | @code{BGE}, @code{BGT}, @code{BLE}, and @code{BLT} for bitwise comparisons; | |
986 | @code{DSHIFTL} and @code{DSHIFTR} for combined left and right shifts, | |
987 | @code{MASKL} and @code{MASKR} for simple left and right justified masks, | |
988 | @code{MERGE_BITS} for a bitwise merge using a mask, @code{SHIFTA}, | |
989 | @code{SHIFTL} and @code{SHIFTR} for shift operations, and the | |
990 | transformational bit intrinsics @code{IALL}, @code{IANY} and @code{IPARITY}. | |
991 | ||
992 | @item Support of the @code{EXECUTE_COMMAND_LINE} intrinsic subroutine. | |
993 | ||
994 | @item Support for the @code{STORAGE_SIZE} intrinsic inquiry function. | |
995 | ||
996 | @item The @code{INT@{8,16,32@}} and @code{REAL@{32,64,128@}} kind type | |
e9853e1c TB |
997 | parameters and the array-valued named constants @code{INTEGER_KINDS}, |
998 | @code{LOGICAL_KINDS}, @code{REAL_KINDS} and @code{CHARACTER_KINDS} of | |
999 | the intrinsic module @code{ISO_FORTRAN_ENV}. | |
1000 | ||
1001 | @item The module procedures @code{C_SIZEOF} of the intrinsic module | |
1002 | @code{ISO_C_BINDINGS} and @code{COMPILER_VERSION} and @code{COMPILER_OPTIONS} | |
1003 | of @code{ISO_FORTRAN_ENV}. | |
3994c6b1 TB |
1004 | |
1005 | @item Experimental coarray support (for one image only), use the | |
1006 | @option{-fcoarray=single} flag to enable it. | |
1007 | ||
1008 | @item The @code{BLOCK} construct is supported. | |
1009 | ||
1010 | @item The @code{STOP} and the new @code{ERROR STOP} statements now | |
1011 | support all constant expressions. | |
1012 | ||
1013 | @item Support for the @code{CONTIGUOUS} attribute. | |
1014 | ||
1015 | @item Support for @code{ALLOCATE} with @code{MOLD}. | |
1016 | ||
1017 | @item Support for the @code{IMPURE} attribute for procedures, which | |
1018 | allows for @code{ELEMENTAL} procedures without the restrictions of | |
1019 | @code{PURE}. | |
1020 | ||
1021 | @item Null pointers (including @code{NULL()}) and not-allocated variables | |
1022 | can be used as actual argument to optional non-pointer, non-allocatable | |
1023 | dummy arguments, denoting an absent argument. | |
1024 | ||
1025 | @item Non-pointer variables with @code{TARGET} attribute can be used as | |
1026 | actual argument to @code{POINTER} dummies with @code{INTENT(IN)}. | |
1027 | ||
1028 | @item Pointers including procedure pointers and those in a derived | |
1029 | type (pointer components) can now be initialized by a target instead | |
1030 | of only by @code{NULL}. | |
1031 | ||
1032 | @item The @code{EXIT} statement (with construct-name) can be now be | |
1033 | used to leave not only the @code{DO} but also the @code{ASSOCIATE}, | |
1034 | @code{BLOCK}, @code{IF}, @code{SELECT CASE} and @code{SELECT TYPE} | |
1035 | constructs. | |
1036 | ||
1037 | @item Internal procedures can now be used as actual argument. | |
1038 | ||
1039 | @item Minor features: obsolesce diagnostics for @code{ENTRY} with | |
1040 | @option{-std=f2008}; a line may start with a semicolon; for internal | |
1041 | and module procedures @code{END} can be used instead of | |
1042 | @code{END SUBROUTINE} and @code{END FUNCTION}; @code{SELECTED_REAL_KIND} | |
1043 | now also takes a @code{RADIX} argument; intrinsic types are supported | |
1044 | for @code{TYPE}(@var{intrinsic-type-spec}); multiple type-bound procedures | |
1045 | can be declared in a single @code{PROCEDURE} statement; implied-shape | |
1046 | arrays are supported for named constants (@code{PARAMETER}). | |
1047 | @end itemize | |
f489fba1 | 1048 | |
26ef2b42 | 1049 | |
71810d0e DK |
1050 | |
1051 | @c --------------------------------------------------------------------- | |
1052 | @c Compiler Characteristics | |
1053 | @c --------------------------------------------------------------------- | |
1054 | ||
1055 | @node Compiler Characteristics | |
1056 | @chapter Compiler Characteristics | |
1057 | ||
927f4842 JB |
1058 | This chapter describes certain characteristics of the GNU Fortran |
1059 | compiler, that are not specified by the Fortran standard, but which | |
1060 | might in some way or another become visible to the programmer. | |
71810d0e DK |
1061 | |
1062 | @menu | |
1063 | * KIND Type Parameters:: | |
927f4842 | 1064 | * Internal representation of LOGICAL variables:: |
85883d65 | 1065 | * Thread-safety of the runtime library:: |
71810d0e DK |
1066 | @end menu |
1067 | ||
1068 | ||
1069 | @node KIND Type Parameters | |
1070 | @section KIND Type Parameters | |
1071 | @cindex kind | |
1072 | ||
1073 | The @code{KIND} type parameters supported by GNU Fortran for the primitive | |
1074 | data types are: | |
1075 | ||
1076 | @table @code | |
1077 | ||
1078 | @item INTEGER | |
1079 | 1, 2, 4, 8*, 16*, default: 4 (1) | |
1080 | ||
1081 | @item LOGICAL | |
1082 | 1, 2, 4, 8*, 16*, default: 4 (1) | |
1083 | ||
1084 | @item REAL | |
6a683de1 | 1085 | 4, 8, 10*, 16*, default: 4 (2) |
71810d0e DK |
1086 | |
1087 | @item COMPLEX | |
6a683de1 | 1088 | 4, 8, 10*, 16*, default: 4 (2) |
71810d0e DK |
1089 | |
1090 | @item CHARACTER | |
1091 | 1, 4, default: 1 | |
1092 | ||
1093 | @end table | |
1094 | ||
1095 | @noindent | |
1096 | * = not available on all systems @* | |
71810d0e DK |
1097 | (1) Unless -fdefault-integer-8 is used @* |
1098 | (2) Unless -fdefault-real-8 is used | |
1099 | ||
1100 | @noindent | |
1101 | The @code{KIND} value matches the storage size in bytes, except for | |
1102 | @code{COMPLEX} where the storage size is twice as much (or both real and | |
1103 | imaginary part are a real value of the given size). It is recommended to use | |
6a683de1 TB |
1104 | the @code{SELECTED_CHAR_KIND}, @code{SELECTED_INT_KIND} and |
1105 | @code{SELECTED_REAL_KIND} intrinsics or the @code{INT8}, @code{INT16}, | |
1106 | @code{INT32}, @code{INT64}, @code{REAL32}, @code{REAL64}, and @code{REAL128} | |
1107 | parameters of the @code{ISO_FORTRAN_ENV} module instead of the concrete values. | |
1108 | The available kind parameters can be found in the constant arrays | |
1109 | @code{CHARACTER_KINDS}, @code{INTEGER_KINDS}, @code{LOGICAL_KINDS} and | |
1110 | @code{REAL_KINDS} in the @code{ISO_FORTRAN_ENV} module | |
1111 | (see @ref{ISO_FORTRAN_ENV}). | |
71810d0e DK |
1112 | |
1113 | ||
927f4842 JB |
1114 | @node Internal representation of LOGICAL variables |
1115 | @section Internal representation of LOGICAL variables | |
1116 | @cindex logical, variable representation | |
1117 | ||
1118 | The Fortran standard does not specify how variables of @code{LOGICAL} | |
1119 | type are represented, beyond requiring that @code{LOGICAL} variables | |
1120 | of default kind have the same storage size as default @code{INTEGER} | |
1121 | and @code{REAL} variables. The GNU Fortran internal representation is | |
1122 | as follows. | |
1123 | ||
1124 | A @code{LOGICAL(KIND=N)} variable is represented as an | |
1125 | @code{INTEGER(KIND=N)} variable, however, with only two permissible | |
1126 | values: @code{1} for @code{.TRUE.} and @code{0} for | |
3994c6b1 | 1127 | @code{.FALSE.}. Any other integer value results in undefined behavior. |
927f4842 JB |
1128 | |
1129 | Note that for mixed-language programming using the | |
1130 | @code{ISO_C_BINDING} feature, there is a @code{C_BOOL} kind that can | |
1131 | be used to create @code{LOGICAL(KIND=C_BOOL)} variables which are | |
1132 | interoperable with the C99 _Bool type. The C99 _Bool type has an | |
1133 | internal representation described in the C99 standard, which is | |
1134 | identical to the above description, i.e. with 1 for true and 0 for | |
1135 | false being the only permissible values. Thus the internal | |
1136 | representation of @code{LOGICAL} variables in GNU Fortran is identical | |
1137 | to C99 _Bool, except for a possible difference in storage size | |
1138 | depending on the kind. | |
1139 | ||
6985b4a1 JB |
1140 | |
1141 | @node Thread-safety of the runtime library | |
1142 | @section Thread-safety of the runtime library | |
1143 | @cindex thread-safety, threads | |
1144 | ||
159c2794 | 1145 | GNU Fortran can be used in programs with multiple threads, e.g.@: by |
6985b4a1 JB |
1146 | using OpenMP, by calling OS thread handling functions via the |
1147 | @code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code | |
1148 | being called from a multi-threaded program. | |
1149 | ||
f3f2c465 | 1150 | The GNU Fortran runtime library, (@code{libgfortran}), supports being |
6985b4a1 JB |
1151 | called concurrently from multiple threads with the following |
1152 | exceptions. | |
1153 | ||
f3f2c465 JB |
1154 | During library initialization, the C @code{getenv} function is used, |
1155 | which need not be thread-safe. Similarly, the @code{getenv} | |
6985b4a1 JB |
1156 | function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and |
1157 | @code{GETENV} intrinsics. It is the responsibility of the user to | |
1158 | ensure that the environment is not being updated concurrently when any | |
1159 | of these actions are taking place. | |
1160 | ||
1161 | The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are | |
f3f2c465 | 1162 | implemented with the @code{system} function, which need not be |
6985b4a1 | 1163 | thread-safe. It is the responsibility of the user to ensure that |
f3f2c465 | 1164 | @code{system} is not called concurrently. |
6985b4a1 | 1165 | |
f3f2c465 JB |
1166 | Finally, for platforms not supporting thread-safe POSIX functions, |
1167 | further functionality might not be thread-safe. For details, please | |
1168 | consult the documentation for your operating system. | |
6985b4a1 | 1169 | |
294fbfc8 TS |
1170 | @c --------------------------------------------------------------------- |
1171 | @c Extensions | |
1172 | @c --------------------------------------------------------------------- | |
1173 | ||
1174 | @c Maybe this chapter should be merged with the 'Standards' section, | |
1175 | @c whenever that is written :-) | |
1176 | ||
1177 | @node Extensions | |
1178 | @chapter Extensions | |
49309826 FXC |
1179 | @cindex extensions |
1180 | ||
1181 | The two sections below detail the extensions to standard Fortran that are | |
1182 | implemented in GNU Fortran, as well as some of the popular or | |
1183 | historically important extensions that are not (or not yet) implemented. | |
1184 | For the latter case, we explain the alternatives available to GNU Fortran | |
1185 | users, including replacement by standard-conforming code or GNU | |
1186 | extensions. | |
1187 | ||
1188 | @menu | |
1189 | * Extensions implemented in GNU Fortran:: | |
1190 | * Extensions not implemented in GNU Fortran:: | |
1191 | @end menu | |
1192 | ||
1193 | ||
1194 | @node Extensions implemented in GNU Fortran | |
1195 | @section Extensions implemented in GNU Fortran | |
1196 | @cindex extensions, implemented | |
294fbfc8 | 1197 | |
7fc15ba5 | 1198 | GNU Fortran implements a number of extensions over standard |
3994c6b1 | 1199 | Fortran. This chapter contains information on their syntax and |
7fc15ba5 | 1200 | meaning. There are currently two categories of GNU Fortran |
c0309c74 | 1201 | extensions, those that provide functionality beyond that provided |
7fc15ba5 | 1202 | by any standard, and those that are supported by GNU Fortran |
c0309c74 RS |
1203 | purely for backward compatibility with legacy compilers. By default, |
1204 | @option{-std=gnu} allows the compiler to accept both types of | |
1205 | extensions, but to warn about the use of the latter. Specifying | |
f489fba1 FXC |
1206 | either @option{-std=f95}, @option{-std=f2003} or @option{-std=f2008} |
1207 | disables both types of extensions, and @option{-std=legacy} allows both | |
1208 | without warning. | |
294fbfc8 TS |
1209 | |
1210 | @menu | |
1211 | * Old-style kind specifications:: | |
1212 | * Old-style variable initialization:: | |
670026fb | 1213 | * Extensions to namelist:: |
11de78ff | 1214 | * X format descriptor without count field:: |
ec8a1940 | 1215 | * Commas in FORMAT specifications:: |
c9f4aa97 | 1216 | * Missing period in FORMAT specifications:: |
ec8a1940 | 1217 | * I/O item lists:: |
11de78ff | 1218 | * BOZ literal constants:: |
5a17346a | 1219 | * @code{Q} exponent-letter:: |
ec8a1940 RS |
1220 | * Real array indices:: |
1221 | * Unary operators:: | |
11de78ff | 1222 | * Implicitly convert LOGICAL and INTEGER values:: |
bc192c77 | 1223 | * Hollerith constants support:: |
83d890b9 | 1224 | * Cray pointers:: |
181c9f4a | 1225 | * CONVERT specifier:: |
6c7a4dfd | 1226 | * OpenMP:: |
d60e76db | 1227 | * Argument list functions:: |
294fbfc8 | 1228 | @end menu |
6de9cd9a | 1229 | |
294fbfc8 | 1230 | @node Old-style kind specifications |
49309826 | 1231 | @subsection Old-style kind specifications |
e739dfac | 1232 | @cindex kind, old-style |
294fbfc8 | 1233 | |
3994c6b1 | 1234 | GNU Fortran allows old-style kind specifications in declarations. These |
b69862d1 | 1235 | look like: |
294fbfc8 | 1236 | @smallexample |
b69862d1 | 1237 | TYPESPEC*size x,y,z |
294fbfc8 | 1238 | @end smallexample |
b2b81a3f | 1239 | @noindent |
11de78ff | 1240 | where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL}, |
b2b81a3f BM |
1241 | etc.), and where @code{size} is a byte count corresponding to the |
1242 | storage size of a valid kind for that type. (For @code{COMPLEX} | |
1243 | variables, @code{size} is the total size of the real and imaginary | |
1244 | parts.) The statement then declares @code{x}, @code{y} and @code{z} to | |
1245 | be of type @code{TYPESPEC} with the appropriate kind. This is | |
1246 | equivalent to the standard-conforming declaration | |
294fbfc8 TS |
1247 | @smallexample |
1248 | TYPESPEC(k) x,y,z | |
1249 | @end smallexample | |
b2b81a3f | 1250 | @noindent |
aad9c4f4 AM |
1251 | where @code{k} is the kind parameter suitable for the intended precision. As |
1252 | kind parameters are implementation-dependent, use the @code{KIND}, | |
1253 | @code{SELECTED_INT_KIND} and @code{SELECTED_REAL_KIND} intrinsics to retrieve | |
1254 | the correct value, for instance @code{REAL*8 x} can be replaced by: | |
1255 | @smallexample | |
1256 | INTEGER, PARAMETER :: dbl = KIND(1.0d0) | |
1257 | REAL(KIND=dbl) :: x | |
1258 | @end smallexample | |
294fbfc8 TS |
1259 | |
1260 | @node Old-style variable initialization | |
49309826 | 1261 | @subsection Old-style variable initialization |
294fbfc8 | 1262 | |
7fc15ba5 | 1263 | GNU Fortran allows old-style initialization of variables of the |
294fbfc8 TS |
1264 | form: |
1265 | @smallexample | |
11de78ff BM |
1266 | INTEGER i/1/,j/2/ |
1267 | REAL x(2,2) /3*0.,1./ | |
294fbfc8 | 1268 | @end smallexample |
11de78ff | 1269 | The syntax for the initializers is as for the @code{DATA} statement, but |
294fbfc8 | 1270 | unlike in a @code{DATA} statement, an initializer only applies to the |
11de78ff BM |
1271 | variable immediately preceding the initialization. In other words, |
1272 | something like @code{INTEGER I,J/2,3/} is not valid. This style of | |
1273 | initialization is only allowed in declarations without double colons | |
1274 | (@code{::}); the double colons were introduced in Fortran 90, which also | |
0979f01d | 1275 | introduced a standard syntax for initializing variables in type |
11de78ff BM |
1276 | declarations. |
1277 | ||
1278 | Examples of standard-conforming code equivalent to the above example | |
1279 | are: | |
294fbfc8 TS |
1280 | @smallexample |
1281 | ! Fortran 90 | |
11de78ff BM |
1282 | INTEGER :: i = 1, j = 2 |
1283 | REAL :: x(2,2) = RESHAPE((/0.,0.,0.,1./),SHAPE(x)) | |
294fbfc8 | 1284 | ! Fortran 77 |
11de78ff BM |
1285 | INTEGER i, j |
1286 | REAL x(2,2) | |
1287 | DATA i/1/, j/2/, x/3*0.,1./ | |
294fbfc8 | 1288 | @end smallexample |
6de9cd9a | 1289 | |
11de78ff BM |
1290 | Note that variables which are explicitly initialized in declarations |
1291 | or in @code{DATA} statements automatically acquire the @code{SAVE} | |
1292 | attribute. | |
9618502b | 1293 | |
670026fb | 1294 | @node Extensions to namelist |
49309826 | 1295 | @subsection Extensions to namelist |
670026fb PT |
1296 | @cindex Namelist |
1297 | ||
7fc15ba5 | 1298 | GNU Fortran fully supports the Fortran 95 standard for namelist I/O |
670026fb PT |
1299 | including array qualifiers, substrings and fully qualified derived types. |
1300 | The output from a namelist write is compatible with namelist read. The | |
1301 | output has all names in upper case and indentation to column 1 after the | |
1302 | namelist name. Two extensions are permitted: | |
1303 | ||
11de78ff | 1304 | Old-style use of @samp{$} instead of @samp{&} |
670026fb PT |
1305 | @smallexample |
1306 | $MYNML | |
1307 | X(:)%Y(2) = 1.0 2.0 3.0 | |
1308 | CH(1:4) = "abcd" | |
1309 | $END | |
1310 | @end smallexample | |
1311 | ||
11de78ff BM |
1312 | It should be noted that the default terminator is @samp{/} rather than |
1313 | @samp{&END}. | |
670026fb | 1314 | |
3994c6b1 | 1315 | Querying of the namelist when inputting from stdin. After at least |
11de78ff | 1316 | one space, entering @samp{?} sends to stdout the namelist name and the names of |
670026fb PT |
1317 | the variables in the namelist: |
1318 | @smallexample | |
11de78ff | 1319 | ? |
670026fb PT |
1320 | |
1321 | &mynml | |
1322 | x | |
1323 | x%y | |
1324 | ch | |
1325 | &end | |
1326 | @end smallexample | |
1327 | ||
11de78ff BM |
1328 | Entering @samp{=?} outputs the namelist to stdout, as if |
1329 | @code{WRITE(*,NML = mynml)} had been called: | |
670026fb PT |
1330 | @smallexample |
1331 | =? | |
1332 | ||
1333 | &MYNML | |
1334 | X(1)%Y= 0.000000 , 1.000000 , 0.000000 , | |
1335 | X(2)%Y= 0.000000 , 2.000000 , 0.000000 , | |
1336 | X(3)%Y= 0.000000 , 3.000000 , 0.000000 , | |
1337 | CH=abcd, / | |
1338 | @end smallexample | |
1339 | ||
5724da63 | 1340 | To aid this dialog, when input is from stdin, errors send their |
11de78ff | 1341 | messages to stderr and execution continues, even if @code{IOSTAT} is set. |
670026fb | 1342 | |
11de78ff BM |
1343 | @code{PRINT} namelist is permitted. This causes an error if |
1344 | @option{-std=f95} is used. | |
21d7d31f PT |
1345 | @smallexample |
1346 | PROGRAM test_print | |
1347 | REAL, dimension (4) :: x = (/1.0, 2.0, 3.0, 4.0/) | |
1348 | NAMELIST /mynml/ x | |
1349 | PRINT mynml | |
1350 | END PROGRAM test_print | |
1351 | @end smallexample | |
1352 | ||
11de78ff BM |
1353 | Expanded namelist reads are permitted. This causes an error if |
1354 | @option{-std=f95} is used. In the following example, the first element | |
1355 | of the array will be given the value 0.00 and the two succeeding | |
1356 | elements will be given the values 1.00 and 2.00. | |
c9f4aa97 JD |
1357 | @smallexample |
1358 | &MYNML | |
1359 | X(1,1) = 0.00 , 1.00 , 2.00 | |
1360 | / | |
1361 | @end smallexample | |
1362 | ||
11de78ff | 1363 | @node X format descriptor without count field |
49309826 | 1364 | @subsection @code{X} format descriptor without count field |
ec8a1940 | 1365 | |
11de78ff BM |
1366 | To support legacy codes, GNU Fortran permits the count field of the |
1367 | @code{X} edit descriptor in @code{FORMAT} statements to be omitted. | |
1368 | When omitted, the count is implicitly assumed to be one. | |
ec8a1940 RS |
1369 | |
1370 | @smallexample | |
1371 | PRINT 10, 2, 3 | |
1372 | 10 FORMAT (I1, X, I1) | |
1373 | @end smallexample | |
1374 | ||
1375 | @node Commas in FORMAT specifications | |
49309826 | 1376 | @subsection Commas in @code{FORMAT} specifications |
ec8a1940 | 1377 | |
7fc15ba5 | 1378 | To support legacy codes, GNU Fortran allows the comma separator |
ec8a1940 | 1379 | to be omitted immediately before and after character string edit |
11de78ff | 1380 | descriptors in @code{FORMAT} statements. |
ec8a1940 RS |
1381 | |
1382 | @smallexample | |
1383 | PRINT 10, 2, 3 | |
1384 | 10 FORMAT ('FOO='I1' BAR='I2) | |
1385 | @end smallexample | |
1386 | ||
c9f4aa97 JD |
1387 | |
1388 | @node Missing period in FORMAT specifications | |
49309826 | 1389 | @subsection Missing period in @code{FORMAT} specifications |
c9f4aa97 | 1390 | |
7fc15ba5 | 1391 | To support legacy codes, GNU Fortran allows missing periods in format |
11de78ff BM |
1392 | specifications if and only if @option{-std=legacy} is given on the |
1393 | command line. This is considered non-conforming code and is | |
1394 | discouraged. | |
c9f4aa97 JD |
1395 | |
1396 | @smallexample | |
1397 | REAL :: value | |
1398 | READ(*,10) value | |
1399 | 10 FORMAT ('F4') | |
1400 | @end smallexample | |
1401 | ||
ec8a1940 | 1402 | @node I/O item lists |
49309826 | 1403 | @subsection I/O item lists |
ec8a1940 RS |
1404 | @cindex I/O item lists |
1405 | ||
7fc15ba5 | 1406 | To support legacy codes, GNU Fortran allows the input item list |
11de78ff BM |
1407 | of the @code{READ} statement, and the output item lists of the |
1408 | @code{WRITE} and @code{PRINT} statements, to start with a comma. | |
ec8a1940 | 1409 | |
5a17346a SK |
1410 | @node @code{Q} exponent-letter |
1411 | @subsection @code{Q} exponent-letter | |
1412 | @cindex @code{Q} exponent-letter | |
1413 | ||
1414 | GNU Fortran accepts real literal constants with an exponent-letter | |
1415 | of @code{Q}, for example, @code{1.23Q45}. The constant is interpreted | |
1416 | as a @code{REAL(16)} entity on targets that suppports this type. If | |
1417 | the target does not support @code{REAL(16)} but has a @code{REAL(10)} | |
1418 | type, then the real-literal-constant will be interpreted as a | |
1419 | @code{REAL(10)} entity. In the absence of @code{REAL(16)} and | |
1420 | @code{REAL(10)}, an error will occur. | |
1421 | ||
11de78ff | 1422 | @node BOZ literal constants |
49309826 | 1423 | @subsection BOZ literal constants |
11de78ff | 1424 | @cindex BOZ literal constants |
ec8a1940 | 1425 | |
00a4618b | 1426 | Besides decimal constants, Fortran also supports binary (@code{b}), |
3994c6b1 | 1427 | octal (@code{o}) and hexadecimal (@code{z}) integer constants. The |
00a4618b TB |
1428 | syntax is: @samp{prefix quote digits quote}, were the prefix is |
1429 | either @code{b}, @code{o} or @code{z}, quote is either @code{'} or | |
1430 | @code{"} and the digits are for binary @code{0} or @code{1}, for | |
1431 | octal between @code{0} and @code{7}, and for hexadecimal between | |
3994c6b1 | 1432 | @code{0} and @code{F}. (Example: @code{b'01011101'}.) |
00a4618b TB |
1433 | |
1434 | Up to Fortran 95, BOZ literals were only allowed to initialize | |
3994c6b1 | 1435 | integer variables in DATA statements. Since Fortran 2003 BOZ literals |
00a4618b TB |
1436 | are also allowed as argument of @code{REAL}, @code{DBLE}, @code{INT} |
1437 | and @code{CMPLX}; the result is the same as if the integer BOZ | |
1438 | literal had been converted by @code{TRANSFER} to, respectively, | |
1439 | @code{real}, @code{double precision}, @code{integer} or @code{complex}. | |
7f59aaba TB |
1440 | As GNU Fortran extension the intrinsic procedures @code{FLOAT}, |
1441 | @code{DFLOAT}, @code{COMPLEX} and @code{DCMPLX} are treated alike. | |
00a4618b | 1442 | |
11de78ff | 1443 | As an extension, GNU Fortran allows hexadecimal BOZ literal constants to |
00a4618b | 1444 | be specified using the @code{X} prefix, in addition to the standard |
3994c6b1 | 1445 | @code{Z} prefix. The BOZ literal can also be specified by adding a |
00a4618b TB |
1446 | suffix to the string, for example, @code{Z'ABC'} and @code{'ABC'Z} are |
1447 | equivalent. | |
1448 | ||
1449 | Furthermore, GNU Fortran allows using BOZ literal constants outside | |
1450 | DATA statements and the four intrinsic functions allowed by Fortran 2003. | |
1451 | In DATA statements, in direct assignments, where the right-hand side | |
1452 | only contains a BOZ literal constant, and for old-style initializers of | |
1453 | the form @code{integer i /o'0173'/}, the constant is transferred | |
c7abc45c | 1454 | as if @code{TRANSFER} had been used; for @code{COMPLEX} numbers, only |
3994c6b1 | 1455 | the real part is initialized unless @code{CMPLX} is used. In all other |
c7abc45c | 1456 | cases, the BOZ literal constant is converted to an @code{INTEGER} value with |
00a4618b TB |
1457 | the largest decimal representation. This value is then converted |
1458 | numerically to the type and kind of the variable in question. | |
9e0667cd | 1459 | (For instance, @code{real :: r = b'0000001' + 1} initializes @code{r} |
00a4618b TB |
1460 | with @code{2.0}.) As different compilers implement the extension |
1461 | differently, one should be careful when doing bitwise initialization | |
1462 | of non-integer variables. | |
1463 | ||
1464 | Note that initializing an @code{INTEGER} variable with a statement such | |
1465 | as @code{DATA i/Z'FFFFFFFF'/} will give an integer overflow error rather | |
11de78ff BM |
1466 | than the desired result of @math{-1} when @code{i} is a 32-bit integer |
1467 | on a system that supports 64-bit integers. The @samp{-fno-range-check} | |
1468 | option can be used as a workaround for legacy code that initializes | |
1469 | integers in this manner. | |
ec8a1940 RS |
1470 | |
1471 | @node Real array indices | |
49309826 | 1472 | @subsection Real array indices |
e739dfac | 1473 | @cindex array, indices of type real |
ec8a1940 | 1474 | |
11de78ff BM |
1475 | As an extension, GNU Fortran allows the use of @code{REAL} expressions |
1476 | or variables as array indices. | |
ec8a1940 RS |
1477 | |
1478 | @node Unary operators | |
49309826 | 1479 | @subsection Unary operators |
e739dfac | 1480 | @cindex operators, unary |
ec8a1940 | 1481 | |
11de78ff BM |
1482 | As an extension, GNU Fortran allows unary plus and unary minus operators |
1483 | to appear as the second operand of binary arithmetic operators without | |
1484 | the need for parenthesis. | |
ec8a1940 RS |
1485 | |
1486 | @smallexample | |
1487 | X = Y * -Z | |
1488 | @end smallexample | |
1489 | ||
11de78ff | 1490 | @node Implicitly convert LOGICAL and INTEGER values |
49309826 | 1491 | @subsection Implicitly convert @code{LOGICAL} and @code{INTEGER} values |
e739dfac DF |
1492 | @cindex conversion, to integer |
1493 | @cindex conversion, to logical | |
c3a29423 | 1494 | |
11de78ff BM |
1495 | As an extension for backwards compatibility with other compilers, GNU |
1496 | Fortran allows the implicit conversion of @code{LOGICAL} values to | |
1497 | @code{INTEGER} values and vice versa. When converting from a | |
1498 | @code{LOGICAL} to an @code{INTEGER}, @code{.FALSE.} is interpreted as | |
1499 | zero, and @code{.TRUE.} is interpreted as one. When converting from | |
1500 | @code{INTEGER} to @code{LOGICAL}, the value zero is interpreted as | |
49de9e73 | 1501 | @code{.FALSE.} and any nonzero value is interpreted as @code{.TRUE.}. |
c3a29423 RS |
1502 | |
1503 | @smallexample | |
a8eabe74 DF |
1504 | LOGICAL :: l |
1505 | l = 1 | |
1506 | @end smallexample | |
1507 | @smallexample | |
1508 | INTEGER :: i | |
1509 | i = .TRUE. | |
c3a29423 RS |
1510 | @end smallexample |
1511 | ||
a8eabe74 DF |
1512 | However, there is no implicit conversion of @code{INTEGER} values in |
1513 | @code{if}-statements, nor of @code{LOGICAL} or @code{INTEGER} values | |
1514 | in I/O operations. | |
69130754 | 1515 | |
bc192c77 | 1516 | @node Hollerith constants support |
49309826 | 1517 | @subsection Hollerith constants support |
bc192c77 FW |
1518 | @cindex Hollerith constants |
1519 | ||
11de78ff BM |
1520 | GNU Fortran supports Hollerith constants in assignments, function |
1521 | arguments, and @code{DATA} and @code{ASSIGN} statements. A Hollerith | |
0979f01d | 1522 | constant is written as a string of characters preceded by an integer |
11de78ff BM |
1523 | constant indicating the character count, and the letter @code{H} or |
1524 | @code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER}, | |
1525 | @code{REAL}, or @code{complex}) or @code{LOGICAL} variable. The | |
1526 | constant will be padded or truncated to fit the size of the variable in | |
1527 | which it is stored. | |
bc192c77 | 1528 | |
11de78ff | 1529 | Examples of valid uses of Hollerith constants: |
bc192c77 | 1530 | @smallexample |
11de78ff BM |
1531 | complex*16 x(2) |
1532 | data x /16Habcdefghijklmnop, 16Hqrstuvwxyz012345/ | |
1533 | x(1) = 16HABCDEFGHIJKLMNOP | |
1534 | call foo (4h abc) | |
bc192c77 FW |
1535 | @end smallexample |
1536 | ||
1537 | Invalid Hollerith constants examples: | |
1538 | @smallexample | |
11de78ff BM |
1539 | integer*4 a |
1540 | a = 8H12345678 ! Valid, but the Hollerith constant will be truncated. | |
1541 | a = 0H ! At least one character is needed. | |
bc192c77 FW |
1542 | @end smallexample |
1543 | ||
11de78ff BM |
1544 | In general, Hollerith constants were used to provide a rudimentary |
1545 | facility for handling character strings in early Fortran compilers, | |
1546 | prior to the introduction of @code{CHARACTER} variables in Fortran 77; | |
1547 | in those cases, the standard-compliant equivalent is to convert the | |
1548 | program to use proper character strings. On occasion, there may be a | |
1549 | case where the intent is specifically to initialize a numeric variable | |
1550 | with a given byte sequence. In these cases, the same result can be | |
1551 | obtained by using the @code{TRANSFER} statement, as in this example. | |
1552 | @smallexample | |
1553 | INTEGER(KIND=4) :: a | |
1554 | a = TRANSFER ("abcd", a) ! equivalent to: a = 4Habcd | |
1555 | @end smallexample | |
1556 | ||
1557 | ||
83d890b9 | 1558 | @node Cray pointers |
49309826 FXC |
1559 | @subsection Cray pointers |
1560 | @cindex pointer, Cray | |
83d890b9 AL |
1561 | |
1562 | Cray pointers are part of a non-standard extension that provides a | |
1563 | C-like pointer in Fortran. This is accomplished through a pair of | |
1564 | variables: an integer "pointer" that holds a memory address, and a | |
1565 | "pointee" that is used to dereference the pointer. | |
1566 | ||
1567 | Pointer/pointee pairs are declared in statements of the form: | |
1568 | @smallexample | |
1569 | pointer ( <pointer> , <pointee> ) | |
1570 | @end smallexample | |
1571 | or, | |
1572 | @smallexample | |
1573 | pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ... | |
1574 | @end smallexample | |
1575 | The pointer is an integer that is intended to hold a memory address. | |
1576 | The pointee may be an array or scalar. A pointee can be an assumed | |
8556236b | 1577 | size array---that is, the last dimension may be left unspecified by |
11de78ff BM |
1578 | using a @code{*} in place of a value---but a pointee cannot be an |
1579 | assumed shape array. No space is allocated for the pointee. | |
83d890b9 AL |
1580 | |
1581 | The pointee may have its type declared before or after the pointer | |
1582 | statement, and its array specification (if any) may be declared | |
1583 | before, during, or after the pointer statement. The pointer may be | |
1584 | declared as an integer prior to the pointer statement. However, some | |
1585 | machines have default integer sizes that are different than the size | |
1586 | of a pointer, and so the following code is not portable: | |
1587 | @smallexample | |
1588 | integer ipt | |
1589 | pointer (ipt, iarr) | |
1590 | @end smallexample | |
1591 | If a pointer is declared with a kind that is too small, the compiler | |
1592 | will issue a warning; the resulting binary will probably not work | |
1593 | correctly, because the memory addresses stored in the pointers may be | |
1594 | truncated. It is safer to omit the first line of the above example; | |
1595 | if explicit declaration of ipt's type is omitted, then the compiler | |
1596 | will ensure that ipt is an integer variable large enough to hold a | |
1597 | pointer. | |
1598 | ||
1599 | Pointer arithmetic is valid with Cray pointers, but it is not the same | |
1600 | as C pointer arithmetic. Cray pointers are just ordinary integers, so | |
1601 | the user is responsible for determining how many bytes to add to a | |
1602 | pointer in order to increment it. Consider the following example: | |
1603 | @smallexample | |
1604 | real target(10) | |
1605 | real pointee(10) | |
1606 | pointer (ipt, pointee) | |
1607 | ipt = loc (target) | |
1608 | ipt = ipt + 1 | |
1609 | @end smallexample | |
11de78ff BM |
1610 | The last statement does not set @code{ipt} to the address of |
1611 | @code{target(1)}, as it would in C pointer arithmetic. Adding @code{1} | |
1612 | to @code{ipt} just adds one byte to the address stored in @code{ipt}. | |
83d890b9 AL |
1613 | |
1614 | Any expression involving the pointee will be translated to use the | |
b122dc6a | 1615 | value stored in the pointer as the base address. |
83d890b9 AL |
1616 | |
1617 | To get the address of elements, this extension provides an intrinsic | |
11de78ff BM |
1618 | function @code{LOC()}. The @code{LOC()} function is equivalent to the |
1619 | @code{&} operator in C, except the address is cast to an integer type: | |
83d890b9 AL |
1620 | @smallexample |
1621 | real ar(10) | |
1622 | pointer(ipt, arpte(10)) | |
1623 | real arpte | |
1624 | ipt = loc(ar) ! Makes arpte is an alias for ar | |
1625 | arpte(1) = 1.0 ! Sets ar(1) to 1.0 | |
1626 | @end smallexample | |
3397327c BM |
1627 | The pointer can also be set by a call to the @code{MALLOC} intrinsic |
1628 | (see @ref{MALLOC}). | |
1629 | ||
83d890b9 AL |
1630 | Cray pointees often are used to alias an existing variable. For |
1631 | example: | |
1632 | @smallexample | |
1633 | integer target(10) | |
1634 | integer iarr(10) | |
1635 | pointer (ipt, iarr) | |
1636 | ipt = loc(target) | |
1637 | @end smallexample | |
11de78ff | 1638 | As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for |
3994c6b1 | 1639 | @code{target}. The optimizer, however, will not detect this aliasing, so |
11de78ff BM |
1640 | it is unsafe to use @code{iarr} and @code{target} simultaneously. Using |
1641 | a pointee in any way that violates the Fortran aliasing rules or | |
3994c6b1 | 1642 | assumptions is illegal. It is the user's responsibility to avoid doing |
11de78ff BM |
1643 | this; the compiler works under the assumption that no such aliasing |
1644 | occurs. | |
1645 | ||
1646 | Cray pointers will work correctly when there is no aliasing (i.e., when | |
1647 | they are used to access a dynamically allocated block of memory), and | |
1648 | also in any routine where a pointee is used, but any variable with which | |
1649 | it shares storage is not used. Code that violates these rules may not | |
1650 | run as the user intends. This is not a bug in the optimizer; any code | |
1651 | that violates the aliasing rules is illegal. (Note that this is not | |
1652 | unique to GNU Fortran; any Fortran compiler that supports Cray pointers | |
1653 | will ``incorrectly'' optimize code with illegal aliasing.) | |
1654 | ||
1655 | There are a number of restrictions on the attributes that can be applied | |
1656 | to Cray pointers and pointees. Pointees may not have the | |
1657 | @code{ALLOCATABLE}, @code{INTENT}, @code{OPTIONAL}, @code{DUMMY}, | |
3994c6b1 | 1658 | @code{TARGET}, @code{INTRINSIC}, or @code{POINTER} attributes. Pointers |
11de78ff | 1659 | may not have the @code{DIMENSION}, @code{POINTER}, @code{TARGET}, |
f14b9067 | 1660 | @code{ALLOCATABLE}, @code{EXTERNAL}, or @code{INTRINSIC} attributes, nor |
3994c6b1 | 1661 | may they be function results. Pointees may not occur in more than one |
f14b9067 FXC |
1662 | pointer statement. A pointee cannot be a pointer. Pointees cannot occur |
1663 | in equivalence, common, or data statements. | |
83d890b9 | 1664 | |
11de78ff BM |
1665 | A Cray pointer may also point to a function or a subroutine. For |
1666 | example, the following excerpt is valid: | |
7074ea72 AL |
1667 | @smallexample |
1668 | implicit none | |
1669 | external sub | |
1670 | pointer (subptr,subpte) | |
1671 | external subpte | |
1672 | subptr = loc(sub) | |
1673 | call subpte() | |
1674 | [...] | |
1675 | subroutine sub | |
1676 | [...] | |
1677 | end subroutine sub | |
1678 | @end smallexample | |
1679 | ||
83d890b9 AL |
1680 | A pointer may be modified during the course of a program, and this |
1681 | will change the location to which the pointee refers. However, when | |
1682 | pointees are passed as arguments, they are treated as ordinary | |
1683 | variables in the invoked function. Subsequent changes to the pointer | |
1684 | will not change the base address of the array that was passed. | |
1685 | ||
181c9f4a | 1686 | @node CONVERT specifier |
49309826 FXC |
1687 | @subsection @code{CONVERT} specifier |
1688 | @cindex @code{CONVERT} specifier | |
181c9f4a | 1689 | |
7fc15ba5 | 1690 | GNU Fortran allows the conversion of unformatted data between little- |
181c9f4a | 1691 | and big-endian representation to facilitate moving of data |
eaa90d25 | 1692 | between different systems. The conversion can be indicated with |
181c9f4a | 1693 | the @code{CONVERT} specifier on the @code{OPEN} statement. |
eaa90d25 TK |
1694 | @xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying |
1695 | the data format via an environment variable. | |
181c9f4a TK |
1696 | |
1697 | Valid values for @code{CONVERT} are: | |
1698 | @itemize @w{} | |
1699 | @item @code{CONVERT='NATIVE'} Use the native format. This is the default. | |
1700 | @item @code{CONVERT='SWAP'} Swap between little- and big-endian. | |
eaa90d25 | 1701 | @item @code{CONVERT='LITTLE_ENDIAN'} Use the little-endian representation |
6ccde948 | 1702 | for unformatted files. |
eaa90d25 | 1703 | @item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for |
6ccde948 | 1704 | unformatted files. |
181c9f4a TK |
1705 | @end itemize |
1706 | ||
1707 | Using the option could look like this: | |
1708 | @smallexample | |
1709 | open(file='big.dat',form='unformatted',access='sequential', & | |
1710 | convert='big_endian') | |
1711 | @end smallexample | |
1712 | ||
1713 | The value of the conversion can be queried by using | |
1714 | @code{INQUIRE(CONVERT=ch)}. The values returned are | |
1715 | @code{'BIG_ENDIAN'} and @code{'LITTLE_ENDIAN'}. | |
1716 | ||
1717 | @code{CONVERT} works between big- and little-endian for | |
1718 | @code{INTEGER} values of all supported kinds and for @code{REAL} | |
8a6c4339 | 1719 | on IEEE systems of kinds 4 and 8. Conversion between different |
181c9f4a | 1720 | ``extended double'' types on different architectures such as |
7fc15ba5 | 1721 | m68k and x86_64, which GNU Fortran |
11de78ff BM |
1722 | supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will |
1723 | probably not work. | |
181c9f4a | 1724 | |
eaa90d25 TK |
1725 | @emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT |
1726 | environment variable will override the CONVERT specifier in the | |
1727 | open statement}. This is to give control over data formats to | |
11de78ff | 1728 | users who do not have the source code of their program available. |
eaa90d25 TK |
1729 | |
1730 | Using anything but the native representation for unformatted data | |
1731 | carries a significant speed overhead. If speed in this area matters | |
1732 | to you, it is best if you use this only for data that needs to be | |
1733 | portable. | |
1734 | ||
6c7a4dfd | 1735 | @node OpenMP |
49309826 | 1736 | @subsection OpenMP |
6c7a4dfd JJ |
1737 | @cindex OpenMP |
1738 | ||
3b303683 DF |
1739 | OpenMP (Open Multi-Processing) is an application programming |
1740 | interface (API) that supports multi-platform shared memory | |
1741 | multiprocessing programming in C/C++ and Fortran on many | |
1742 | architectures, including Unix and Microsoft Windows platforms. | |
1743 | It consists of a set of compiler directives, library routines, | |
1744 | and environment variables that influence run-time behavior. | |
1745 | ||
1746 | GNU Fortran strives to be compatible to the | |
9e0667cd TB |
1747 | @uref{http://www.openmp.org/mp-documents/spec30.pdf, |
1748 | OpenMP Application Program Interface v3.0}. | |
3b303683 DF |
1749 | |
1750 | To enable the processing of the OpenMP directive @code{!$omp} in | |
1751 | free-form source code; the @code{c$omp}, @code{*$omp} and @code{!$omp} | |
1752 | directives in fixed form; the @code{!$} conditional compilation sentinels | |
1753 | in free form; and the @code{c$}, @code{*$} and @code{!$} sentinels | |
1754 | in fixed form, @command{gfortran} needs to be invoked with the | |
3994c6b1 | 1755 | @option{-fopenmp}. This also arranges for automatic linking of the |
3b303683 DF |
1756 | GNU OpenMP runtime library @ref{Top,,libgomp,libgomp,GNU OpenMP |
1757 | runtime library}. | |
1758 | ||
1759 | The OpenMP Fortran runtime library routines are provided both in a | |
1760 | form of a Fortran 90 module named @code{omp_lib} and in a form of | |
1761 | a Fortran @code{include} file named @file{omp_lib.h}. | |
1762 | ||
1763 | An example of a parallelized loop taken from Appendix A.1 of | |
1764 | the OpenMP Application Program Interface v2.5: | |
1765 | @smallexample | |
1766 | SUBROUTINE A1(N, A, B) | |
1767 | INTEGER I, N | |
1768 | REAL B(N), A(N) | |
1769 | !$OMP PARALLEL DO !I is private by default | |
1770 | DO I=2,N | |
1771 | B(I) = (A(I) + A(I-1)) / 2.0 | |
1772 | ENDDO | |
1773 | !$OMP END PARALLEL DO | |
1774 | END SUBROUTINE A1 | |
1775 | @end smallexample | |
1776 | ||
1777 | Please note: | |
1778 | @itemize | |
1779 | @item | |
24219f12 | 1780 | @option{-fopenmp} implies @option{-frecursive}, i.e., all local arrays |
3994c6b1 | 1781 | will be allocated on the stack. When porting existing code to OpenMP, |
3b303683 DF |
1782 | this may lead to surprising results, especially to segmentation faults |
1783 | if the stacksize is limited. | |
1784 | ||
1785 | @item | |
9e0667cd | 1786 | On glibc-based systems, OpenMP enabled applications cannot be statically |
3994c6b1 | 1787 | linked due to limitations of the underlying pthreads-implementation. It |
3b303683 DF |
1788 | might be possible to get a working solution if |
1789 | @command{-Wl,--whole-archive -lpthread -Wl,--no-whole-archive} is added | |
3994c6b1 | 1790 | to the command line. However, this is not supported by @command{gcc} and |
3b303683 DF |
1791 | thus not recommended. |
1792 | @end itemize | |
6c7a4dfd | 1793 | |
d60e76db | 1794 | @node Argument list functions |
49309826 | 1795 | @subsection Argument list functions @code{%VAL}, @code{%REF} and @code{%LOC} |
e739dfac | 1796 | @cindex argument list functions |
49309826 FXC |
1797 | @cindex @code{%VAL} |
1798 | @cindex @code{%REF} | |
1799 | @cindex @code{%LOC} | |
d60e76db PT |
1800 | |
1801 | GNU Fortran supports argument list functions @code{%VAL}, @code{%REF} | |
1802 | and @code{%LOC} statements, for backward compatibility with g77. | |
1803 | It is recommended that these should be used only for code that is | |
1804 | accessing facilities outside of GNU Fortran, such as operating system | |
3994c6b1 | 1805 | or windowing facilities. It is best to constrain such uses to isolated |
d60e76db | 1806 | portions of a program--portions that deal specifically and exclusively |
3994c6b1 | 1807 | with low-level, system-dependent facilities. Such portions might well |
d60e76db PT |
1808 | provide a portable interface for use by the program as a whole, but are |
1809 | themselves not portable, and should be thoroughly tested each time they | |
1810 | are rebuilt using a new compiler or version of a compiler. | |
1811 | ||
1812 | @code{%VAL} passes a scalar argument by value, @code{%REF} passes it by | |
1813 | reference and @code{%LOC} passes its memory location. Since gfortran | |
1814 | already passes scalar arguments by reference, @code{%REF} is in effect | |
9e0667cd | 1815 | a do-nothing. @code{%LOC} has the same effect as a Fortran pointer. |
d60e76db PT |
1816 | |
1817 | An example of passing an argument by value to a C subroutine foo.: | |
1818 | @smallexample | |
1819 | C | |
1820 | C prototype void foo_ (float x); | |
1821 | C | |
1822 | external foo | |
1823 | real*4 x | |
1824 | x = 3.14159 | |
1825 | call foo (%VAL (x)) | |
1826 | end | |
1827 | @end smallexample | |
1828 | ||
1829 | For details refer to the g77 manual | |
ab940b73 | 1830 | @uref{http://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}. |
d60e76db | 1831 | |
9e0667cd TB |
1832 | Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the |
1833 | GNU Fortran testsuite are worth a look. | |
49309826 FXC |
1834 | |
1835 | ||
1836 | @node Extensions not implemented in GNU Fortran | |
1837 | @section Extensions not implemented in GNU Fortran | |
1838 | @cindex extensions, not implemented | |
1839 | ||
1840 | The long history of the Fortran language, its wide use and broad | |
1841 | userbase, the large number of different compiler vendors and the lack of | |
1842 | some features crucial to users in the first standards have lead to the | |
aad9c4f4 | 1843 | existence of a number of important extensions to the language. While |
49309826 | 1844 | some of the most useful or popular extensions are supported by the GNU |
aad9c4f4 | 1845 | Fortran compiler, not all existing extensions are supported. This section |
49309826 FXC |
1846 | aims at listing these extensions and offering advice on how best make |
1847 | code that uses them running with the GNU Fortran compiler. | |
1848 | ||
1849 | @c More can be found here: | |
1850 | @c -- http://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/Missing-Features.html | |
9e0667cd | 1851 | @c -- the list of Fortran and libgfortran bugs closed as WONTFIX: |
49309826 FXC |
1852 | @c http://tinyurl.com/2u4h5y |
1853 | ||
1854 | @menu | |
1855 | * STRUCTURE and RECORD:: | |
1856 | @c * UNION and MAP:: | |
1857 | * ENCODE and DECODE statements:: | |
2995ed9a | 1858 | * Variable FORMAT expressions:: |
49309826 FXC |
1859 | @c * Q edit descriptor:: |
1860 | @c * AUTOMATIC statement:: | |
1861 | @c * TYPE and ACCEPT I/O Statements:: | |
1862 | @c * .XOR. operator:: | |
1863 | @c * CARRIAGECONTROL, DEFAULTFILE, DISPOSE and RECORDTYPE I/O specifiers:: | |
f14b9067 FXC |
1864 | @c * Omitted arguments in procedure call:: |
1865 | * Alternate complex function syntax:: | |
49309826 FXC |
1866 | @end menu |
1867 | ||
1868 | ||
1869 | @node STRUCTURE and RECORD | |
1870 | @subsection @code{STRUCTURE} and @code{RECORD} | |
1871 | @cindex @code{STRUCTURE} | |
1872 | @cindex @code{RECORD} | |
1873 | ||
1874 | Structures are user-defined aggregate data types; this functionality was | |
1875 | standardized in Fortran 90 with an different syntax, under the name of | |
3994c6b1 | 1876 | ``derived types''. Here is an example of code using the non portable |
49309826 FXC |
1877 | structure syntax: |
1878 | ||
1879 | @example | |
1880 | ! Declaring a structure named ``item'' and containing three fields: | |
1881 | ! an integer ID, an description string and a floating-point price. | |
1882 | STRUCTURE /item/ | |
1883 | INTEGER id | |
1884 | CHARACTER(LEN=200) description | |
1885 | REAL price | |
1886 | END STRUCTURE | |
1887 | ||
1888 | ! Define two variables, an single record of type ``item'' | |
1889 | ! named ``pear'', and an array of items named ``store_catalog'' | |
1890 | RECORD /item/ pear, store_catalog(100) | |
1891 | ||
1892 | ! We can directly access the fields of both variables | |
1893 | pear.id = 92316 | |
1894 | pear.description = "juicy D'Anjou pear" | |
1895 | pear.price = 0.15 | |
1896 | store_catalog(7).id = 7831 | |
1897 | store_catalog(7).description = "milk bottle" | |
1898 | store_catalog(7).price = 1.2 | |
1899 | ||
aad9c4f4 | 1900 | ! We can also manipulate the whole structure |
49309826 FXC |
1901 | store_catalog(12) = pear |
1902 | print *, store_catalog(12) | |
1903 | @end example | |
1904 | ||
1905 | @noindent | |
1906 | This code can easily be rewritten in the Fortran 90 syntax as following: | |
1907 | ||
1908 | @example | |
1909 | ! ``STRUCTURE /name/ ... END STRUCTURE'' becomes | |
1910 | ! ``TYPE name ... END TYPE'' | |
1911 | TYPE item | |
1912 | INTEGER id | |
1913 | CHARACTER(LEN=200) description | |
1914 | REAL price | |
1915 | END TYPE | |
1916 | ||
1917 | ! ``RECORD /name/ variable'' becomes ``TYPE(name) variable'' | |
1918 | TYPE(item) pear, store_catalog(100) | |
1919 | ||
1920 | ! Instead of using a dot (.) to access fields of a record, the | |
1921 | ! standard syntax uses a percent sign (%) | |
1922 | pear%id = 92316 | |
1923 | pear%description = "juicy D'Anjou pear" | |
1924 | pear%price = 0.15 | |
1925 | store_catalog(7)%id = 7831 | |
1926 | store_catalog(7)%description = "milk bottle" | |
1927 | store_catalog(7)%price = 1.2 | |
1928 | ||
1929 | ! Assignments of a whole variable don't change | |
1930 | store_catalog(12) = pear | |
1931 | print *, store_catalog(12) | |
1932 | @end example | |
1933 | ||
1934 | ||
1935 | @c @node UNION and MAP | |
1936 | @c @subsection @code{UNION} and @code{MAP} | |
1937 | @c @cindex @code{UNION} | |
1938 | @c @cindex @code{MAP} | |
1939 | @c | |
1940 | @c For help writing this one, see | |
1941 | @c http://www.eng.umd.edu/~nsw/ench250/fortran1.htm#UNION and | |
1942 | @c http://www.tacc.utexas.edu/services/userguides/pgi/pgiws_ug/pgi32u06.htm | |
1943 | ||
1944 | ||
1945 | @node ENCODE and DECODE statements | |
1946 | @subsection @code{ENCODE} and @code{DECODE} statements | |
1947 | @cindex @code{ENCODE} | |
1948 | @cindex @code{DECODE} | |
1949 | ||
1950 | GNU Fortran doesn't support the @code{ENCODE} and @code{DECODE} | |
1951 | statements. These statements are best replaced by @code{READ} and | |
1952 | @code{WRITE} statements involving internal files (@code{CHARACTER} | |
1953 | variables and arrays), which have been part of the Fortran standard since | |
3994c6b1 | 1954 | Fortran 77. For example, replace a code fragment like |
49309826 FXC |
1955 | |
1956 | @smallexample | |
1957 | INTEGER*1 LINE(80) | |
1958 | REAL A, B, C | |
1959 | c ... Code that sets LINE | |
1960 | DECODE (80, 9000, LINE) A, B, C | |
1961 | 9000 FORMAT (1X, 3(F10.5)) | |
1962 | @end smallexample | |
1963 | ||
1964 | @noindent | |
1965 | with the following: | |
1966 | ||
1967 | @smallexample | |
1968 | CHARACTER(LEN=80) LINE | |
1969 | REAL A, B, C | |
1970 | c ... Code that sets LINE | |
1971 | READ (UNIT=LINE, FMT=9000) A, B, C | |
1972 | 9000 FORMAT (1X, 3(F10.5)) | |
1973 | @end smallexample | |
1974 | ||
1975 | Similarly, replace a code fragment like | |
1976 | ||
1977 | @smallexample | |
1978 | INTEGER*1 LINE(80) | |
1979 | REAL A, B, C | |
1980 | c ... Code that sets A, B and C | |
1981 | ENCODE (80, 9000, LINE) A, B, C | |
1982 | 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) | |
1983 | @end smallexample | |
1984 | ||
1985 | @noindent | |
1986 | with the following: | |
1987 | ||
1988 | @smallexample | |
3fe9e1ff | 1989 | CHARACTER(LEN=80) LINE |
49309826 FXC |
1990 | REAL A, B, C |
1991 | c ... Code that sets A, B and C | |
1992 | WRITE (UNIT=LINE, FMT=9000) A, B, C | |
1993 | 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) | |
1994 | @end smallexample | |
1995 | ||
1996 | ||
2995ed9a FXC |
1997 | @node Variable FORMAT expressions |
1998 | @subsection Variable @code{FORMAT} expressions | |
1999 | @cindex @code{FORMAT} | |
2000 | ||
2001 | A variable @code{FORMAT} expression is format statement which includes | |
3994c6b1 TB |
2002 | angle brackets enclosing a Fortran expression: @code{FORMAT(I<N>)}. GNU |
2003 | Fortran does not support this legacy extension. The effect of variable | |
2995ed9a | 2004 | format expressions can be reproduced by using the more powerful (and |
3994c6b1 | 2005 | standard) combination of internal output and string formats. For example, |
2995ed9a FXC |
2006 | replace a code fragment like this: |
2007 | ||
2008 | @smallexample | |
2009 | WRITE(6,20) INT1 | |
2010 | 20 FORMAT(I<N+1>) | |
2011 | @end smallexample | |
2012 | ||
2013 | @noindent | |
2014 | with the following: | |
2015 | ||
2016 | @smallexample | |
2017 | c Variable declaration | |
87187539 | 2018 | CHARACTER(LEN=20) FMT |
2995ed9a FXC |
2019 | c |
2020 | c Other code here... | |
2021 | c | |
2022 | WRITE(FMT,'("(I", I0, ")")') N+1 | |
87187539 | 2023 | WRITE(6,FMT) INT1 |
2995ed9a FXC |
2024 | @end smallexample |
2025 | ||
2026 | @noindent | |
2027 | or with: | |
2028 | ||
2029 | @smallexample | |
2030 | c Variable declaration | |
2031 | CHARACTER(LEN=20) FMT | |
2032 | c | |
2033 | c Other code here... | |
2034 | c | |
2035 | WRITE(FMT,*) N+1 | |
2036 | WRITE(6,"(I" // ADJUSTL(FMT) // ")") INT1 | |
2037 | @end smallexample | |
2038 | ||
2039 | ||
f14b9067 FXC |
2040 | @node Alternate complex function syntax |
2041 | @subsection Alternate complex function syntax | |
2042 | @cindex Complex function | |
2043 | ||
2044 | Some Fortran compilers, including @command{g77}, let the user declare | |
2045 | complex functions with the syntax @code{COMPLEX FUNCTION name*16()}, as | |
3994c6b1 TB |
2046 | well as @code{COMPLEX*16 FUNCTION name()}. Both are non-standard, legacy |
2047 | extensions. @command{gfortran} accepts the latter form, which is more | |
f14b9067 FXC |
2048 | common, but not the former. |
2049 | ||
2050 | ||
2051 | ||
9e0667cd TB |
2052 | @c --------------------------------------------------------------------- |
2053 | @c Mixed-Language Programming | |
2054 | @c --------------------------------------------------------------------- | |
2055 | ||
2056 | @node Mixed-Language Programming | |
2057 | @chapter Mixed-Language Programming | |
2058 | @cindex Interoperability | |
2059 | @cindex Mixed-language programming | |
2060 | ||
2061 | @menu | |
2062 | * Interoperability with C:: | |
08a6b8e0 | 2063 | * GNU Fortran Compiler Directives:: |
9e0667cd TB |
2064 | * Non-Fortran Main Program:: |
2065 | @end menu | |
2066 | ||
2067 | This chapter is about mixed-language interoperability, but also applies | |
3994c6b1 | 2068 | if one links Fortran code compiled by different compilers. In most cases, |
9e0667cd TB |
2069 | use of the C Binding features of the Fortran 2003 standard is sufficient, |
2070 | and their use is highly recommended. | |
2071 | ||
2072 | ||
2073 | @node Interoperability with C | |
2074 | @section Interoperability with C | |
2075 | ||
2076 | @menu | |
2077 | * Intrinsic Types:: | |
9e0667cd TB |
2078 | * Derived Types and struct:: |
2079 | * Interoperable Global Variables:: | |
2080 | * Interoperable Subroutines and Functions:: | |
da4dbc25 DK |
2081 | * Working with Pointers:: |
2082 | * Further Interoperability of Fortran with C:: | |
9e0667cd TB |
2083 | @end menu |
2084 | ||
2085 | Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a | |
2086 | standardized way to generate procedure and derived-type | |
2087 | declarations and global variables which are interoperable with C | |
3994c6b1 | 2088 | (ISO/IEC 9899:1999). The @code{bind(C)} attribute has been added |
9e0667cd | 2089 | to inform the compiler that a symbol shall be interoperable with C; |
3994c6b1 TB |
2090 | also, some constraints are added. Note, however, that not |
2091 | all C features have a Fortran equivalent or vice versa. For instance, | |
9e0667cd TB |
2092 | neither C's unsigned integers nor C's functions with variable number |
2093 | of arguments have an equivalent in Fortran. | |
2094 | ||
c7d9f803 | 2095 | Note that array dimensions are reversely ordered in C and that arrays in |
96c49324 | 2096 | C always start with index 0 while in Fortran they start by default with |
3994c6b1 | 2097 | 1. Thus, an array declaration @code{A(n,m)} in Fortran matches |
96c49324 | 2098 | @code{A[m][n]} in C and accessing the element @code{A(i,j)} matches |
3994c6b1 | 2099 | @code{A[j-1][i-1]}. The element following @code{A(i,j)} (C: @code{A[j-1][i-1]}; |
96c49324 | 2100 | assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}). |
9e0667cd TB |
2101 | |
2102 | @node Intrinsic Types | |
2103 | @subsection Intrinsic Types | |
2104 | ||
2105 | In order to ensure that exactly the same variable type and kind is used | |
2106 | in C and Fortran, the named constants shall be used which are defined in the | |
3994c6b1 | 2107 | @code{ISO_C_BINDING} intrinsic module. That module contains named constants |
9e0667cd | 2108 | for kind parameters and character named constants for the escape sequences |
3994c6b1 | 2109 | in C. For a list of the constants, see @ref{ISO_C_BINDING}. |
9e0667cd TB |
2110 | |
2111 | @node Derived Types and struct | |
2112 | @subsection Derived Types and struct | |
2113 | ||
2114 | For compatibility of derived types with @code{struct}, one needs to use | |
3994c6b1 | 2115 | the @code{BIND(C)} attribute in the type declaration. For instance, the |
9e0667cd TB |
2116 | following type declaration |
2117 | ||
2118 | @smallexample | |
2119 | USE ISO_C_BINDING | |
2120 | TYPE, BIND(C) :: myType | |
2121 | INTEGER(C_INT) :: i1, i2 | |
2122 | INTEGER(C_SIGNED_CHAR) :: i3 | |
2123 | REAL(C_DOUBLE) :: d1 | |
2124 | COMPLEX(C_FLOAT_COMPLEX) :: c1 | |
2125 | CHARACTER(KIND=C_CHAR) :: str(5) | |
2126 | END TYPE | |
2127 | @end smallexample | |
2128 | ||
2129 | matches the following @code{struct} declaration in C | |
2130 | ||
2131 | @smallexample | |
2132 | struct @{ | |
2133 | int i1, i2; | |
2134 | /* Note: "char" might be signed or unsigned. */ | |
2135 | signed char i3; | |
2136 | double d1; | |
2137 | float _Complex c1; | |
2138 | char str[5]; | |
2139 | @} myType; | |
2140 | @end smallexample | |
2141 | ||
2142 | Derived types with the C binding attribute shall not have the @code{sequence} | |
2143 | attribute, type parameters, the @code{extends} attribute, nor type-bound | |
3994c6b1 TB |
2144 | procedures. Every component must be of interoperable type and kind and may not |
2145 | have the @code{pointer} or @code{allocatable} attribute. The names of the | |
9e0667cd TB |
2146 | variables are irrelevant for interoperability. |
2147 | ||
2148 | As there exist no direct Fortran equivalents, neither unions nor structs | |
2149 | with bit field or variable-length array members are interoperable. | |
2150 | ||
2151 | @node Interoperable Global Variables | |
2152 | @subsection Interoperable Global Variables | |
2153 | ||
2154 | Variables can be made accessible from C using the C binding attribute, | |
3994c6b1 | 2155 | optionally together with specifying a binding name. Those variables |
9e0667cd TB |
2156 | have to be declared in the declaration part of a @code{MODULE}, |
2157 | be of interoperable type, and have neither the @code{pointer} nor | |
2158 | the @code{allocatable} attribute. | |
2159 | ||
2160 | @smallexample | |
2161 | MODULE m | |
2162 | USE myType_module | |
2163 | USE ISO_C_BINDING | |
2164 | integer(C_INT), bind(C, name="_MyProject_flags") :: global_flag | |
2165 | type(myType), bind(C) :: tp | |
2166 | END MODULE | |
2167 | @end smallexample | |
2168 | ||
2169 | Here, @code{_MyProject_flags} is the case-sensitive name of the variable | |
2170 | as seen from C programs while @code{global_flag} is the case-insensitive | |
3994c6b1 | 2171 | name as seen from Fortran. If no binding name is specified, as for |
9e0667cd TB |
2172 | @var{tp}, the C binding name is the (lowercase) Fortran binding name. |
2173 | If a binding name is specified, only a single variable may be after the | |
3994c6b1 | 2174 | double colon. Note of warning: You cannot use a global variable to |
9e0667cd | 2175 | access @var{errno} of the C library as the C standard allows it to be |
3994c6b1 | 2176 | a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead. |
9e0667cd TB |
2177 | |
2178 | @node Interoperable Subroutines and Functions | |
2179 | @subsection Interoperable Subroutines and Functions | |
2180 | ||
2181 | Subroutines and functions have to have the @code{BIND(C)} attribute to | |
3994c6b1 TB |
2182 | be compatible with C. The dummy argument declaration is relatively |
2183 | straightforward. However, one needs to be careful because C uses | |
20460eb9 | 2184 | call-by-value by default while Fortran behaves usually similar to |
3994c6b1 TB |
2185 | call-by-reference. Furthermore, strings and pointers are handled |
2186 | differently. Note that only explicit size and assumed-size arrays are | |
20460eb9 | 2187 | supported but not assumed-shape or allocatable arrays. |
9e0667cd TB |
2188 | |
2189 | To pass a variable by value, use the @code{VALUE} attribute. | |
2190 | Thus the following C prototype | |
2191 | ||
2192 | @smallexample | |
2193 | @code{int func(int i, int *j)} | |
2194 | @end smallexample | |
2195 | ||
2196 | matches the Fortran declaration | |
2197 | ||
2198 | @smallexample | |
dae5882f TB |
2199 | integer(c_int) function func(i,j) |
2200 | use iso_c_binding, only: c_int | |
2201 | integer(c_int), VALUE :: i | |
2202 | integer(c_int) :: j | |
9e0667cd TB |
2203 | @end smallexample |
2204 | ||
da4dbc25 DK |
2205 | Note that pointer arguments also frequently need the @code{VALUE} attribute, |
2206 | see @ref{Working with Pointers}. | |
9e0667cd | 2207 | |
3994c6b1 | 2208 | Strings are handled quite differently in C and Fortran. In C a string |
9e0667cd TB |
2209 | is a @code{NUL}-terminated array of characters while in Fortran each string |
2210 | has a length associated with it and is thus not terminated (by e.g. | |
3994c6b1 | 2211 | @code{NUL}). For example, if one wants to use the following C function, |
9e0667cd TB |
2212 | |
2213 | @smallexample | |
2214 | #include <stdio.h> | |
2215 | void print_C(char *string) /* equivalent: char string[] */ | |
2216 | @{ | |
2217 | printf("%s\n", string); | |
2218 | @} | |
2219 | @end smallexample | |
2220 | ||
2221 | to print ``Hello World'' from Fortran, one can call it using | |
2222 | ||
2223 | @smallexample | |
2224 | use iso_c_binding, only: C_CHAR, C_NULL_CHAR | |
2225 | interface | |
2226 | subroutine print_c(string) bind(C, name="print_C") | |
2227 | use iso_c_binding, only: c_char | |
2228 | character(kind=c_char) :: string(*) | |
2229 | end subroutine print_c | |
2230 | end interface | |
2231 | call print_c(C_CHAR_"Hello World"//C_NULL_CHAR) | |
2232 | @end smallexample | |
2233 | ||
2234 | As the example shows, one needs to ensure that the | |
3994c6b1 | 2235 | string is @code{NUL} terminated. Additionally, the dummy argument |
9e0667cd | 2236 | @var{string} of @code{print_C} is a length-one assumed-size |
3994c6b1 | 2237 | array; using @code{character(len=*)} is not allowed. The example |
9e0667cd TB |
2238 | above uses @code{c_char_"Hello World"} to ensure the string |
2239 | literal has the right type; typically the default character | |
2240 | kind and @code{c_char} are the same and thus @code{"Hello World"} | |
3994c6b1 | 2241 | is equivalent. However, the standard does not guarantee this. |
9e0667cd | 2242 | |
da4dbc25 | 2243 | The use of strings is now further illustrated using the C library |
9e0667cd TB |
2244 | function @code{strncpy}, whose prototype is |
2245 | ||
2246 | @smallexample | |
2247 | char *strncpy(char *restrict s1, const char *restrict s2, size_t n); | |
2248 | @end smallexample | |
2249 | ||
2250 | The function @code{strncpy} copies at most @var{n} characters from | |
3994c6b1 | 2251 | string @var{s2} to @var{s1} and returns @var{s1}. In the following |
9e0667cd TB |
2252 | example, we ignore the return value: |
2253 | ||
2254 | @smallexample | |
2255 | use iso_c_binding | |
2256 | implicit none | |
2257 | character(len=30) :: str,str2 | |
2258 | interface | |
2259 | ! Ignore the return value of strncpy -> subroutine | |
2260 | ! "restrict" is always assumed if we do not pass a pointer | |
2261 | subroutine strncpy(dest, src, n) bind(C) | |
2262 | import | |
2263 | character(kind=c_char), intent(out) :: dest(*) | |
2264 | character(kind=c_char), intent(in) :: src(*) | |
2265 | integer(c_size_t), value, intent(in) :: n | |
2266 | end subroutine strncpy | |
2267 | end interface | |
2268 | str = repeat('X',30) ! Initialize whole string with 'X' | |
2269 | call strncpy(str, c_char_"Hello World"//C_NULL_CHAR, & | |
2270 | len(c_char_"Hello World",kind=c_size_t)) | |
2271 | print '(a)', str ! prints: "Hello WorldXXXXXXXXXXXXXXXXXXX" | |
2272 | end | |
2273 | @end smallexample | |
2274 | ||
da4dbc25 DK |
2275 | The intrinsic procedures are described in @ref{Intrinsic Procedures}. |
2276 | ||
2277 | @node Working with Pointers | |
2278 | @subsection Working with Pointers | |
2279 | ||
2280 | C pointers are represented in Fortran via the special opaque derived type | |
3994c6b1 | 2281 | @code{type(c_ptr)} (with private components). Thus one needs to |
9e0667cd TB |
2282 | use intrinsic conversion procedures to convert from or to C pointers. |
2283 | For example, | |
2284 | ||
2285 | @smallexample | |
2286 | use iso_c_binding | |
2287 | type(c_ptr) :: cptr1, cptr2 | |
2288 | integer, target :: array(7), scalar | |
2289 | integer, pointer :: pa(:), ps | |
2290 | cptr1 = c_loc(array(1)) ! The programmer needs to ensure that the | |
2291 | ! array is contiguous if required by the C | |
2292 | ! procedure | |
2293 | cptr2 = c_loc(scalar) | |
2294 | call c_f_pointer(cptr2, ps) | |
2295 | call c_f_pointer(cptr2, pa, shape=[7]) | |
2296 | @end smallexample | |
2297 | ||
2298 | When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument | |
da4dbc25 DK |
2299 | has to be passed. |
2300 | ||
2301 | If a pointer is a dummy-argument of an interoperable procedure, it usually | |
2302 | has to be declared using the @code{VALUE} attribute. @code{void*} | |
2303 | matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone | |
2304 | matches @code{void**}. | |
9e0667cd TB |
2305 | |
2306 | Procedure pointers are handled analogously to pointers; the C type is | |
2307 | @code{TYPE(C_FUNPTR)} and the intrinsic conversion procedures are | |
da4dbc25 | 2308 | @code{C_F_PROCPOINTER} and @code{C_FUNLOC}. |
9e0667cd | 2309 | |
da4dbc25 DK |
2310 | Let's consider two examples of actually passing a procedure pointer from |
2311 | C to Fortran and vice versa. Note that these examples are also very | |
2312 | similar to passing ordinary pointers between both languages. | |
2313 | First, consider this code in C: | |
2314 | ||
2315 | @smallexample | |
2316 | /* Procedure implemented in Fortran. */ | |
2317 | void get_values (void (*)(double)); | |
2318 | ||
2319 | /* Call-back routine we want called from Fortran. */ | |
2320 | void | |
2321 | print_it (double x) | |
2322 | @{ | |
2323 | printf ("Number is %f.\n", x); | |
2324 | @} | |
2325 | ||
2326 | /* Call Fortran routine and pass call-back to it. */ | |
2327 | void | |
2328 | foobar () | |
2329 | @{ | |
2330 | get_values (&print_it); | |
2331 | @} | |
2332 | @end smallexample | |
2333 | ||
2334 | A matching implementation for @code{get_values} in Fortran, that correctly | |
2335 | receives the procedure pointer from C and is able to call it, is given | |
2336 | in the following @code{MODULE}: | |
2337 | ||
2338 | @smallexample | |
2339 | MODULE m | |
2340 | IMPLICIT NONE | |
2341 | ||
2342 | ! Define interface of call-back routine. | |
2343 | ABSTRACT INTERFACE | |
2344 | SUBROUTINE callback (x) | |
2345 | USE, INTRINSIC :: ISO_C_BINDING | |
2346 | REAL(KIND=C_DOUBLE), INTENT(IN), VALUE :: x | |
2347 | END SUBROUTINE callback | |
2348 | END INTERFACE | |
2349 | ||
2350 | CONTAINS | |
2351 | ||
2352 | ! Define C-bound procedure. | |
2353 | SUBROUTINE get_values (cproc) BIND(C) | |
2354 | USE, INTRINSIC :: ISO_C_BINDING | |
2355 | TYPE(C_FUNPTR), INTENT(IN), VALUE :: cproc | |
2356 | ||
2357 | PROCEDURE(callback), POINTER :: proc | |
2358 | ||
2359 | ! Convert C to Fortran procedure pointer. | |
2360 | CALL C_F_PROCPOINTER (cproc, proc) | |
2361 | ||
2362 | ! Call it. | |
2363 | CALL proc (1.0_C_DOUBLE) | |
2364 | CALL proc (-42.0_C_DOUBLE) | |
2365 | CALL proc (18.12_C_DOUBLE) | |
2366 | END SUBROUTINE get_values | |
2367 | ||
2368 | END MODULE m | |
2369 | @end smallexample | |
2370 | ||
2371 | Next, we want to call a C routine that expects a procedure pointer argument | |
2372 | and pass it a Fortran procedure (which clearly must be interoperable!). | |
2373 | Again, the C function may be: | |
2374 | ||
2375 | @smallexample | |
2376 | int | |
2377 | call_it (int (*func)(int), int arg) | |
2378 | @{ | |
2379 | return func (arg); | |
2380 | @} | |
2381 | @end smallexample | |
2382 | ||
2383 | It can be used as in the following Fortran code: | |
2384 | ||
2385 | @smallexample | |
2386 | MODULE m | |
2387 | USE, INTRINSIC :: ISO_C_BINDING | |
2388 | IMPLICIT NONE | |
2389 | ||
2390 | ! Define interface of C function. | |
2391 | INTERFACE | |
2392 | INTEGER(KIND=C_INT) FUNCTION call_it (func, arg) BIND(C) | |
2393 | USE, INTRINSIC :: ISO_C_BINDING | |
2394 | TYPE(C_FUNPTR), INTENT(IN), VALUE :: func | |
2395 | INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg | |
2396 | END FUNCTION call_it | |
2397 | END INTERFACE | |
2398 | ||
2399 | CONTAINS | |
2400 | ||
2401 | ! Define procedure passed to C function. | |
2402 | ! It must be interoperable! | |
2403 | INTEGER(KIND=C_INT) FUNCTION double_it (arg) BIND(C) | |
2404 | INTEGER(KIND=C_INT), INTENT(IN), VALUE :: arg | |
2405 | double_it = arg + arg | |
2406 | END FUNCTION double_it | |
2407 | ||
2408 | ! Call C function. | |
2409 | SUBROUTINE foobar () | |
2410 | TYPE(C_FUNPTR) :: cproc | |
2411 | INTEGER(KIND=C_INT) :: i | |
2412 | ||
2413 | ! Get C procedure pointer. | |
2414 | cproc = C_FUNLOC (double_it) | |
2415 | ||
2416 | ! Use it. | |
2417 | DO i = 1_C_INT, 10_C_INT | |
2418 | PRINT *, call_it (cproc, i) | |
2419 | END DO | |
2420 | END SUBROUTINE foobar | |
2421 | ||
2422 | END MODULE m | |
2423 | @end smallexample | |
9e0667cd TB |
2424 | |
2425 | @node Further Interoperability of Fortran with C | |
2426 | @subsection Further Interoperability of Fortran with C | |
2427 | ||
2428 | Assumed-shape and allocatable arrays are passed using an array descriptor | |
3994c6b1 TB |
2429 | (dope vector). The internal structure of the array descriptor used |
2430 | by GNU Fortran is not yet documented and will change. There will also be | |
9e0667cd | 2431 | a Technical Report (TR 29113) which standardizes an interoperable |
3994c6b1 | 2432 | array descriptor. Until then, you can use the Chasm Language |
9e0667cd TB |
2433 | Interoperability Tools, @url{http://chasm-interop.sourceforge.net/}, |
2434 | which provide an interface to GNU Fortran's array descriptor. | |
2435 | ||
2436 | The technical report 29113 will presumably also include support for | |
2437 | C-interoperable @code{OPTIONAL} and for assumed-rank and assumed-type | |
3994c6b1 | 2438 | dummy arguments. However, the TR has neither been approved nor implemented |
9e0667cd TB |
2439 | in GNU Fortran; therefore, these features are not yet available. |
2440 | ||
08a6b8e0 TB |
2441 | |
2442 | ||
2443 | @node GNU Fortran Compiler Directives | |
2444 | @section GNU Fortran Compiler Directives | |
2445 | ||
2446 | The Fortran standard standard describes how a conforming program shall | |
3994c6b1 | 2447 | behave; however, the exact implementation is not standardized. In order |
08a6b8e0 TB |
2448 | to allow the user to choose specific implementation details, compiler |
2449 | directives can be used to set attributes of variables and procedures | |
3994c6b1 | 2450 | which are not part of the standard. Whether a given attribute is |
08a6b8e0 TB |
2451 | supported and its exact effects depend on both the operating system and |
2452 | on the processor; see | |
2453 | @ref{Top,,C Extensions,gcc,Using the GNU Compiler Collection (GCC)} | |
2454 | for details. | |
2455 | ||
2456 | For procedures and procedure pointers, the following attributes can | |
2457 | be used to change the calling convention: | |
2458 | ||
2459 | @itemize | |
2460 | @item @code{CDECL} -- standard C calling convention | |
2461 | @item @code{STDCALL} -- convention where the called procedure pops the stack | |
2462 | @item @code{FASTCALL} -- part of the arguments are passed via registers | |
2463 | instead using the stack | |
2464 | @end itemize | |
2465 | ||
2466 | Besides changing the calling convention, the attributes also influence | |
2467 | the decoration of the symbol name, e.g., by a leading underscore or by | |
3994c6b1 | 2468 | a trailing at-sign followed by the number of bytes on the stack. When |
08a6b8e0 TB |
2469 | assigning a procedure to a procedure pointer, both should use the same |
2470 | calling convention. | |
2471 | ||
2472 | On some systems, procedures and global variables (module variables and | |
2473 | @code{COMMON} blocks) need special handling to be accessible when they | |
3994c6b1 | 2474 | are in a shared library. The following attributes are available: |
08a6b8e0 TB |
2475 | |
2476 | @itemize | |
2477 | @item @code{DLLEXPORT} -- provide a global pointer to a pointer in the DLL | |
2478 | @item @code{DLLIMPORT} -- reference the function or variable using a global pointer | |
2479 | @end itemize | |
2480 | ||
2481 | The attributes are specified using the syntax | |
2482 | ||
2483 | @code{!GCC$ ATTRIBUTES} @var{attribute-list} @code{::} @var{variable-list} | |
2484 | ||
2485 | where in free-form source code only whitespace is allowed before @code{!GCC$} | |
2486 | and in fixed-form source code @code{!GCC$}, @code{cGCC$} or @code{*GCC$} shall | |
2487 | start in the first column. | |
2488 | ||
2489 | For procedures, the compiler directives shall be placed into the body | |
2490 | of the procedure; for variables and procedure pointers, they shall be in | |
2491 | the same declaration part as the variable or procedure pointer. | |
2492 | ||
2493 | ||
2494 | ||
9e0667cd TB |
2495 | @node Non-Fortran Main Program |
2496 | @section Non-Fortran Main Program | |
2497 | ||
2498 | @menu | |
2499 | * _gfortran_set_args:: Save command-line arguments | |
2500 | * _gfortran_set_options:: Set library option flags | |
2501 | * _gfortran_set_convert:: Set endian conversion | |
2502 | * _gfortran_set_record_marker:: Set length of record markers | |
2503 | * _gfortran_set_max_subrecord_length:: Set subrecord length | |
96c49324 | 2504 | * _gfortran_set_fpe:: Set when a Floating Point Exception should be raised |
9e0667cd TB |
2505 | @end menu |
2506 | ||
2507 | Even if you are doing mixed-language programming, it is very | |
2508 | likely that you do not need to know or use the information in this | |
3994c6b1 | 2509 | section. Since it is about the internal structure of GNU Fortran, |
9e0667cd TB |
2510 | it may also change in GCC minor releases. |
2511 | ||
2512 | When you compile a @code{PROGRAM} with GNU Fortran, a function | |
2513 | with the name @code{main} (in the symbol table of the object file) | |
2514 | is generated, which initializes the libgfortran library and then | |
2515 | calls the actual program which uses the name @code{MAIN__}, for | |
3994c6b1 | 2516 | historic reasons. If you link GNU Fortran compiled procedures |
9e0667cd TB |
2517 | to, e.g., a C or C++ program or to a Fortran program compiled by |
2518 | a different compiler, the libgfortran library is not initialized | |
2519 | and thus a few intrinsic procedures do not work properly, e.g. | |
2520 | those for obtaining the command-line arguments. | |
2521 | ||
2522 | Therefore, if your @code{PROGRAM} is not compiled with | |
2523 | GNU Fortran and the GNU Fortran compiled procedures require | |
2524 | intrinsics relying on the library initialization, you need to | |
3994c6b1 | 2525 | initialize the library yourself. Using the default options, |
9e0667cd | 2526 | gfortran calls @code{_gfortran_set_args} and |
3994c6b1 | 2527 | @code{_gfortran_set_options}. The initialization of the former |
9e0667cd TB |
2528 | is needed if the called procedures access the command line |
2529 | (and for backtracing); the latter sets some flags based on the | |
7daa7b1d | 2530 | standard chosen or to disable backtracing. In typical programs, |
9e0667cd TB |
2531 | it is not necessary to call any initialization function. |
2532 | ||
2533 | If your @code{PROGRAM} is compiled with GNU Fortran, you shall | |
3994c6b1 | 2534 | not call any of the following functions. The libgfortran |
9e0667cd TB |
2535 | initialization functions are shown in C syntax but using C |
2536 | bindings they are also accessible from Fortran. | |
2537 | ||
2538 | ||
2539 | @node _gfortran_set_args | |
2540 | @subsection @code{_gfortran_set_args} --- Save command-line arguments | |
2541 | @fnindex _gfortran_set_args | |
2542 | @cindex libgfortran initialization, set_args | |
2543 | ||
2544 | @table @asis | |
2545 | @item @emph{Description}: | |
2546 | @code{_gfortran_set_args} saves the command-line arguments; this | |
2547 | initialization is required if any of the command-line intrinsics | |
3994c6b1 | 2548 | is called. Additionally, it shall be called if backtracing is |
9e0667cd TB |
2549 | enabled (see @code{_gfortran_set_options}). |
2550 | ||
2551 | @item @emph{Syntax}: | |
2552 | @code{void _gfortran_set_args (int argc, char *argv[])} | |
2553 | ||
2554 | @item @emph{Arguments}: | |
2555 | @multitable @columnfractions .15 .70 | |
2556 | @item @var{argc} @tab number of command line argument strings | |
2557 | @item @var{argv} @tab the command-line argument strings; argv[0] | |
2558 | is the pathname of the executable itself. | |
2559 | @end multitable | |
2560 | ||
2561 | @item @emph{Example}: | |
2562 | @smallexample | |
2563 | int main (int argc, char *argv[]) | |
2564 | @{ | |
2565 | /* Initialize libgfortran. */ | |
2566 | _gfortran_set_args (argc, argv); | |
2567 | return 0; | |
2568 | @} | |
2569 | @end smallexample | |
2570 | @end table | |
2571 | ||
2572 | ||
2573 | @node _gfortran_set_options | |
2574 | @subsection @code{_gfortran_set_options} --- Set library option flags | |
2575 | @fnindex _gfortran_set_options | |
2576 | @cindex libgfortran initialization, set_options | |
2577 | ||
2578 | @table @asis | |
2579 | @item @emph{Description}: | |
2580 | @code{_gfortran_set_options} sets several flags related to the Fortran | |
7daa7b1d | 2581 | standard to be used, whether backtracing should be enabled |
3994c6b1 | 2582 | and whether range checks should be performed. The syntax allows for |
9e0667cd | 2583 | upward compatibility since the number of passed flags is specified; for |
3994c6b1 TB |
2584 | non-passed flags, the default value is used. See also |
2585 | @pxref{Code Gen Options}. Please note that not all flags are actually | |
9e0667cd TB |
2586 | used. |
2587 | ||
2588 | @item @emph{Syntax}: | |
2589 | @code{void _gfortran_set_options (int num, int options[])} | |
2590 | ||
2591 | @item @emph{Arguments}: | |
2592 | @multitable @columnfractions .15 .70 | |
2593 | @item @var{num} @tab number of options passed | |
2594 | @item @var{argv} @tab The list of flag values | |
2595 | @end multitable | |
2596 | ||
2597 | @item @emph{option flag list}: | |
2598 | @multitable @columnfractions .15 .70 | |
2599 | @item @var{option}[0] @tab Allowed standard; can give run-time errors | |
2600 | if e.g. an input-output edit descriptor is invalid in a given standard. | |
2601 | Possible values are (bitwise or-ed) @code{GFC_STD_F77} (1), | |
2602 | @code{GFC_STD_F95_OBS} (2), @code{GFC_STD_F95_DEL} (4), @code{GFC_STD_F95} | |
2603 | (8), @code{GFC_STD_F2003} (16), @code{GFC_STD_GNU} (32), | |
58fc89f6 TB |
2604 | @code{GFC_STD_LEGACY} (64), @code{GFC_STD_F2008} (128), and |
2605 | @code{GFC_STD_F2008_OBS} (256). Default: @code{GFC_STD_F95_OBS | |
2606 | | GFC_STD_F95_DEL | GFC_STD_F95 | GFC_STD_F2003 | GFC_STD_F2008 | |
2607 | | GFC_STD_F2008_OBS | GFC_STD_F77 | GFC_STD_GNU | GFC_STD_LEGACY}. | |
9e0667cd | 2608 | @item @var{option}[1] @tab Standard-warning flag; prints a warning to |
3994c6b1 | 2609 | standard error. Default: @code{GFC_STD_F95_DEL | GFC_STD_LEGACY}. |
9e0667cd TB |
2610 | @item @var{option}[2] @tab If non zero, enable pedantic checking. |
2611 | Default: off. | |
7daa7b1d | 2612 | @item @var{option}[3] @tab Unused. |
9e0667cd | 2613 | @item @var{option}[4] @tab If non zero, enable backtracing on run-time |
7daa7b1d | 2614 | errors. Default: enabled. |
9e0667cd TB |
2615 | Note: Installs a signal handler and requires command-line |
2616 | initialization using @code{_gfortran_set_args}. | |
2617 | @item @var{option}[5] @tab If non zero, supports signed zeros. | |
2618 | Default: enabled. | |
3994c6b1 | 2619 | @item @var{option}[6] @tab Enables run-time checking. Possible values |
9e0667cd | 2620 | are (bitwise or-ed): GFC_RTCHECK_BOUNDS (1), GFC_RTCHECK_ARRAY_TEMPS (2), |
20460eb9 | 2621 | GFC_RTCHECK_RECURSION (4), GFC_RTCHECK_DO (16), GFC_RTCHECK_POINTER (32). |
9e0667cd TB |
2622 | Default: disabled. |
2623 | @item @var{option}[7] @tab If non zero, range checking is enabled. | |
3994c6b1 | 2624 | Default: enabled. See -frange-check (@pxref{Code Gen Options}). |
9e0667cd TB |
2625 | @end multitable |
2626 | ||
2627 | @item @emph{Example}: | |
2628 | @smallexample | |
7daa7b1d JB |
2629 | /* Use gfortran 4.7 default options. */ |
2630 | static int options[] = @{68, 255, 0, 0, 1, 1, 0, 1@}; | |
9e0667cd TB |
2631 | _gfortran_set_options (8, &options); |
2632 | @end smallexample | |
2633 | @end table | |
2634 | ||
2635 | ||
2636 | @node _gfortran_set_convert | |
2637 | @subsection @code{_gfortran_set_convert} --- Set endian conversion | |
2638 | @fnindex _gfortran_set_convert | |
2639 | @cindex libgfortran initialization, set_convert | |
2640 | ||
2641 | @table @asis | |
2642 | @item @emph{Description}: | |
2643 | @code{_gfortran_set_convert} set the representation of data for | |
2644 | unformatted files. | |
2645 | ||
2646 | @item @emph{Syntax}: | |
2647 | @code{void _gfortran_set_convert (int conv)} | |
2648 | ||
2649 | @item @emph{Arguments}: | |
2650 | @multitable @columnfractions .15 .70 | |
2651 | @item @var{conv} @tab Endian conversion, possible values: | |
2652 | GFC_CONVERT_NATIVE (0, default), GFC_CONVERT_SWAP (1), | |
2653 | GFC_CONVERT_BIG (2), GFC_CONVERT_LITTLE (3). | |
2654 | @end multitable | |
2655 | ||
2656 | @item @emph{Example}: | |
2657 | @smallexample | |
2658 | int main (int argc, char *argv[]) | |
2659 | @{ | |
2660 | /* Initialize libgfortran. */ | |
2661 | _gfortran_set_args (argc, argv); | |
2662 | _gfortran_set_convert (1); | |
2663 | return 0; | |
2664 | @} | |
2665 | @end smallexample | |
2666 | @end table | |
2667 | ||
2668 | ||
2669 | @node _gfortran_set_record_marker | |
2670 | @subsection @code{_gfortran_set_record_marker} --- Set length of record markers | |
2671 | @fnindex _gfortran_set_record_marker | |
2672 | @cindex libgfortran initialization, set_record_marker | |
2673 | ||
2674 | @table @asis | |
2675 | @item @emph{Description}: | |
96c49324 | 2676 | @code{_gfortran_set_record_marker} sets the length of record markers |
9e0667cd TB |
2677 | for unformatted files. |
2678 | ||
2679 | @item @emph{Syntax}: | |
2680 | @code{void _gfortran_set_record_marker (int val)} | |
2681 | ||
2682 | @item @emph{Arguments}: | |
2683 | @multitable @columnfractions .15 .70 | |
2684 | @item @var{val} @tab Length of the record marker; valid values | |
3994c6b1 | 2685 | are 4 and 8. Default is 4. |
9e0667cd TB |
2686 | @end multitable |
2687 | ||
2688 | @item @emph{Example}: | |
2689 | @smallexample | |
2690 | int main (int argc, char *argv[]) | |
2691 | @{ | |
2692 | /* Initialize libgfortran. */ | |
2693 | _gfortran_set_args (argc, argv); | |
2694 | _gfortran_set_record_marker (8); | |
2695 | return 0; | |
2696 | @} | |
2697 | @end smallexample | |
2698 | @end table | |
2699 | ||
2700 | ||
96c49324 TB |
2701 | @node _gfortran_set_fpe |
2702 | @subsection @code{_gfortran_set_fpe} --- Set when a Floating Point Exception should be raised | |
2703 | @fnindex _gfortran_set_fpe | |
2704 | @cindex libgfortran initialization, set_fpe | |
2705 | ||
2706 | @table @asis | |
2707 | @item @emph{Description}: | |
2708 | @code{_gfortran_set_fpe} sets the IEEE exceptions for which a | |
3994c6b1 | 2709 | Floating Point Exception (FPE) should be raised. On most systems, |
96c49324 TB |
2710 | this will result in a SIGFPE signal being sent and the program |
2711 | being interrupted. | |
2712 | ||
2713 | @item @emph{Syntax}: | |
2714 | @code{void _gfortran_set_fpe (int val)} | |
2715 | ||
2716 | @item @emph{Arguments}: | |
2717 | @multitable @columnfractions .15 .70 | |
3994c6b1 | 2718 | @item @var{option}[0] @tab IEEE exceptions. Possible values are |
96c49324 TB |
2719 | (bitwise or-ed) zero (0, default) no trapping, |
2720 | @code{GFC_FPE_INVALID} (1), @code{GFC_FPE_DENORMAL} (2), | |
2721 | @code{GFC_FPE_ZERO} (4), @code{GFC_FPE_OVERFLOW} (8), | |
2722 | @code{GFC_FPE_UNDERFLOW} (16), and @code{GFC_FPE_PRECISION} (32). | |
2723 | @end multitable | |
2724 | ||
2725 | @item @emph{Example}: | |
2726 | @smallexample | |
2727 | int main (int argc, char *argv[]) | |
2728 | @{ | |
2729 | /* Initialize libgfortran. */ | |
2730 | _gfortran_set_args (argc, argv); | |
2731 | /* FPE for invalid operations such as SQRT(-1.0). */ | |
2732 | _gfortran_set_fpe (1); | |
2733 | return 0; | |
2734 | @} | |
2735 | @end smallexample | |
2736 | @end table | |
2737 | ||
2738 | ||
9e0667cd TB |
2739 | @node _gfortran_set_max_subrecord_length |
2740 | @subsection @code{_gfortran_set_max_subrecord_length} --- Set subrecord length | |
2741 | @fnindex _gfortran_set_max_subrecord_length | |
2742 | @cindex libgfortran initialization, set_max_subrecord_length | |
2743 | ||
2744 | @table @asis | |
2745 | @item @emph{Description}: | |
2746 | @code{_gfortran_set_max_subrecord_length} set the maximum length | |
3994c6b1 | 2747 | for a subrecord. This option only makes sense for testing and |
9e0667cd TB |
2748 | debugging of unformatted I/O. |
2749 | ||
2750 | @item @emph{Syntax}: | |
2751 | @code{void _gfortran_set_max_subrecord_length (int val)} | |
2752 | ||
2753 | @item @emph{Arguments}: | |
2754 | @multitable @columnfractions .15 .70 | |
2755 | @item @var{val} @tab the maximum length for a subrecord; | |
2756 | the maximum permitted value is 2147483639, which is also | |
2757 | the default. | |
2758 | @end multitable | |
2759 | ||
2760 | @item @emph{Example}: | |
2761 | @smallexample | |
2762 | int main (int argc, char *argv[]) | |
2763 | @{ | |
2764 | /* Initialize libgfortran. */ | |
2765 | _gfortran_set_args (argc, argv); | |
2766 | _gfortran_set_max_subrecord_length (8); | |
2767 | return 0; | |
2768 | @} | |
2769 | @end smallexample | |
2770 | @end table | |
2771 | ||
2995ed9a FXC |
2772 | |
2773 | ||
c8cf50e4 | 2774 | @c Intrinsic Procedures |
a63dad5b TS |
2775 | @c --------------------------------------------------------------------- |
2776 | ||
c8cf50e4 BM |
2777 | @include intrinsic.texi |
2778 | ||
2779 | ||
2780 | @tex | |
2781 | \blankpart | |
2782 | @end tex | |
2783 | ||
6de9cd9a DN |
2784 | @c --------------------------------------------------------------------- |
2785 | @c Contributing | |
2786 | @c --------------------------------------------------------------------- | |
2787 | ||
2788 | @node Contributing | |
c8cf50e4 | 2789 | @unnumbered Contributing |
6de9cd9a DN |
2790 | @cindex Contributing |
2791 | ||
2792 | Free software is only possible if people contribute to efforts | |
2793 | to create it. | |
2794 | We're always in need of more people helping out with ideas | |
2795 | and comments, writing documentation and contributing code. | |
2796 | ||
7fc15ba5 | 2797 | If you want to contribute to GNU Fortran, |
6de9cd9a DN |
2798 | have a look at the long lists of projects you can take on. |
2799 | Some of these projects are small, | |
2800 | some of them are large; | |
2801 | some are completely orthogonal to the rest of what is | |
7fc15ba5 | 2802 | happening on GNU Fortran, |
6de9cd9a DN |
2803 | but others are ``mainstream'' projects in need of enthusiastic hackers. |
2804 | All of these projects are important! | |
2805 | We'll eventually get around to the things here, | |
2806 | but they are also things doable by someone who is willing and able. | |
2807 | ||
2808 | @menu | |
2809 | * Contributors:: | |
2810 | * Projects:: | |
c8cf50e4 | 2811 | * Proposed Extensions:: |
6de9cd9a DN |
2812 | @end menu |
2813 | ||
2814 | ||
2815 | @node Contributors | |
7fc15ba5 | 2816 | @section Contributors to GNU Fortran |
6de9cd9a DN |
2817 | @cindex Contributors |
2818 | @cindex Credits | |
2819 | @cindex Authors | |
2820 | ||
2821 | Most of the parser was hand-crafted by @emph{Andy Vaught}, who is | |
2822 | also the initiator of the whole project. Thanks Andy! | |
2823 | Most of the interface with GCC was written by @emph{Paul Brook}. | |
2824 | ||
2825 | The following individuals have contributed code and/or | |
7fc15ba5 | 2826 | ideas and significant help to the GNU Fortran project |
3b303683 | 2827 | (in alphabetical order): |
6de9cd9a DN |
2828 | |
2829 | @itemize @minus | |
3b303683 | 2830 | @item Janne Blomqvist |
6de9cd9a | 2831 | @item Steven Bosscher |
6de9cd9a | 2832 | @item Paul Brook |
3b303683 | 2833 | @item Tobias Burnus |
deeddce6 | 2834 | @item Fran@,{c}ois-Xavier Coudert |
3b303683 DF |
2835 | @item Bud Davis |
2836 | @item Jerry DeLisle | |
cf6ae955 | 2837 | @item Erik Edelmann |
3b303683 DF |
2838 | @item Bernhard Fischer |
2839 | @item Daniel Franke | |
2840 | @item Richard Guenther | |
2841 | @item Richard Henderson | |
2842 | @item Katherine Holcomb | |
2843 | @item Jakub Jelinek | |
2844 | @item Niels Kristian Bech Jensen | |
2845 | @item Steven Johnson | |
2846 | @item Steven G. Kargl | |
cf6ae955 SB |
2847 | @item Thomas Koenig |
2848 | @item Asher Langton | |
3b303683 DF |
2849 | @item H. J. Lu |
2850 | @item Toon Moene | |
2851 | @item Brooks Moses | |
2852 | @item Andrew Pinski | |
2853 | @item Tim Prince | |
2854 | @item Christopher D. Rickett | |
deeddce6 | 2855 | @item Richard Sandiford |
3b303683 DF |
2856 | @item Tobias Schl@"uter |
2857 | @item Roger Sayle | |
2858 | @item Paul Thomas | |
2859 | @item Andy Vaught | |
2860 | @item Feng Wang | |
2861 | @item Janus Weil | |
9e0667cd | 2862 | @item Daniel Kraft |
6de9cd9a DN |
2863 | @end itemize |
2864 | ||
2865 | The following people have contributed bug reports, | |
2866 | smaller or larger patches, | |
2867 | and much needed feedback and encouragement for the | |
7fc15ba5 | 2868 | GNU Fortran project: |
6de9cd9a DN |
2869 | |
2870 | @itemize @minus | |
6de9cd9a | 2871 | @item Bill Clodius |
49309826 | 2872 | @item Dominique d'Humi@`eres |
6de9cd9a | 2873 | @item Kate Hedstrom |
3b303683 | 2874 | @item Erik Schnetter |
9e0667cd | 2875 | @item Joost VandeVondele |
6de9cd9a DN |
2876 | @end itemize |
2877 | ||
2878 | Many other individuals have helped debug, | |
7fc15ba5 | 2879 | test and improve the GNU Fortran compiler over the past few years, |
ed499b9f | 2880 | and we welcome you to do the same! |
6de9cd9a DN |
2881 | If you already have done so, |
2882 | and you would like to see your name listed in the | |
2883 | list above, please contact us. | |
2884 | ||
2885 | ||
2886 | @node Projects | |
2887 | @section Projects | |
2888 | ||
2889 | @table @emph | |
2890 | ||
2891 | @item Help build the test suite | |
49309826 FXC |
2892 | Solicit more code for donation to the test suite: the more extensive the |
2893 | testsuite, the smaller the risk of breaking things in the future! We can | |
2894 | keep code private on request. | |
6de9cd9a DN |
2895 | |
2896 | @item Bug hunting/squishing | |
49309826 FXC |
2897 | Find bugs and write more test cases! Test cases are especially very |
2898 | welcome, because it allows us to concentrate on fixing bugs instead of | |
3994c6b1 TB |
2899 | isolating them. Going through the bugzilla database at |
2900 | @url{http://gcc.gnu.org/@/bugzilla/} to reduce testcases posted there and | |
49309826 FXC |
2901 | add more information (for example, for which version does the testcase |
2902 | work, for which versions does it fail?) is also very helpful. | |
6de9cd9a | 2903 | |
49309826 | 2904 | @end table |
6de9cd9a DN |
2905 | |
2906 | ||
c8cf50e4 BM |
2907 | @node Proposed Extensions |
2908 | @section Proposed Extensions | |
6de9cd9a | 2909 | |
c8cf50e4 BM |
2910 | Here's a list of proposed extensions for the GNU Fortran compiler, in no particular |
2911 | order. Most of these are necessary to be fully compatible with | |
2912 | existing Fortran compilers, but they are not part of the official | |
2913 | J3 Fortran 95 standard. | |
6de9cd9a | 2914 | |
c8cf50e4 BM |
2915 | @subsection Compiler extensions: |
2916 | @itemize @bullet | |
2917 | @item | |
2918 | User-specified alignment rules for structures. | |
6de9cd9a | 2919 | |
c8cf50e4 BM |
2920 | @item |
2921 | Automatically extend single precision constants to double. | |
e014df90 | 2922 | |
c8cf50e4 BM |
2923 | @item |
2924 | Compile code that conserves memory by dynamically allocating common and | |
2925 | module storage either on stack or heap. | |
e014df90 | 2926 | |
c8cf50e4 BM |
2927 | @item |
2928 | Compile flag to generate code for array conformance checking (suggest -CC). | |
e014df90 | 2929 | |
c8cf50e4 BM |
2930 | @item |
2931 | User control of symbol names (underscores, etc). | |
e014df90 | 2932 | |
c8cf50e4 BM |
2933 | @item |
2934 | Compile setting for maximum size of stack frame size before spilling | |
2935 | parts to static or heap. | |
e014df90 | 2936 | |
a63dad5b | 2937 | @item |
c8cf50e4 | 2938 | Flag to force local variables into static space. |
e27edcd4 TK |
2939 | |
2940 | @item | |
c8cf50e4 | 2941 | Flag to force local variables onto stack. |
c8cf50e4 BM |
2942 | @end itemize |
2943 | ||
2944 | ||
2945 | @subsection Environment Options | |
2946 | @itemize @bullet | |
aa08038d | 2947 | @item |
c8cf50e4 BM |
2948 | Pluggable library modules for random numbers, linear algebra. |
2949 | LA should use BLAS calling conventions. | |
2950 | ||
8e119f1b | 2951 | @item |
c8cf50e4 BM |
2952 | Environment variables controlling actions on arithmetic exceptions like |
2953 | overflow, underflow, precision loss---Generate NaN, abort, default. | |
2954 | action. | |
2955 | ||
da1e2517 | 2956 | @item |
c8cf50e4 | 2957 | Set precision for fp units that support it (i387). |
aa08038d | 2958 | |
ffcba571 | 2959 | @item |
c8cf50e4 | 2960 | Variable for setting fp rounding mode. |
ffcba571 | 2961 | |
08d7f64e | 2962 | @item |
c8cf50e4 BM |
2963 | Variable to fill uninitialized variables with a user-defined bit |
2964 | pattern. | |
08d7f64e | 2965 | |
669353d5 | 2966 | @item |
c8cf50e4 BM |
2967 | Environment variable controlling filename that is opened for that unit |
2968 | number. | |
669353d5 TB |
2969 | |
2970 | @item | |
c8cf50e4 | 2971 | Environment variable to clear/trash memory being freed. |
669353d5 | 2972 | |
08d7f64e | 2973 | @item |
c8cf50e4 | 2974 | Environment variable to control tracing of allocations and frees. |
ffcba571 | 2975 | |
8998be20 | 2976 | @item |
c8cf50e4 | 2977 | Environment variable to display allocated memory at normal program end. |
8998be20 | 2978 | |
669353d5 | 2979 | @item |
c8cf50e4 BM |
2980 | Environment variable for filename for * IO-unit. |
2981 | ||
2982 | @item | |
2983 | Environment variable for temporary file directory. | |
2984 | ||
2985 | @item | |
2986 | Environment variable forcing standard output to be line buffered (unix). | |
ffcba571 | 2987 | |
e014df90 JB |
2988 | @end itemize |
2989 | ||
2990 | ||
a63dad5b TS |
2991 | @c --------------------------------------------------------------------- |
2992 | @c GNU General Public License | |
2993 | @c --------------------------------------------------------------------- | |
2994 | ||
7f9766e4 | 2995 | @include gpl_v3.texi |
a63dad5b TS |
2996 | |
2997 | ||
2998 | ||
2999 | @c --------------------------------------------------------------------- | |
3000 | @c GNU Free Documentation License | |
3001 | @c --------------------------------------------------------------------- | |
3002 | ||
3003 | @include fdl.texi | |
3004 | ||
3005 | ||
3006 | ||
3007 | @c --------------------------------------------------------------------- | |
3008 | @c Funding Free Software | |
3009 | @c --------------------------------------------------------------------- | |
3010 | ||
3011 | @include funding.texi | |
3012 | ||
e014df90 | 3013 | @c --------------------------------------------------------------------- |
32864778 | 3014 | @c Indices |
e014df90 | 3015 | @c --------------------------------------------------------------------- |
6de9cd9a | 3016 | |
32864778 | 3017 | @node Option Index |
e739dfac | 3018 | @unnumbered Option Index |
67948fd2 | 3019 | @command{gfortran}'s command line options are indexed here without any |
3994c6b1 | 3020 | initial @samp{-} or @samp{--}. Where an option has both positive and |
67948fd2 BM |
3021 | negative forms (such as -foption and -fno-option), relevant entries in |
3022 | the manual are indexed under the most appropriate form; it may sometimes | |
3023 | be useful to look up both forms. | |
32864778 DF |
3024 | @printindex op |
3025 | ||
3026 | @node Keyword Index | |
e739dfac | 3027 | @unnumbered Keyword Index |
6de9cd9a DN |
3028 | @printindex cp |
3029 | ||
3030 | @bye |