1 \input texinfo @c -*-texinfo-*-
5 @set last-update 2004-03-21
6 @set copyrights-g77 1995,1996,1997,1998,1999,2000,2001,2002,2003,2004
10 @c This tells @include'd files that they're part of the overall G77 doc
11 @c set. (They might be part of a higher-level doc set too.)
14 @c @setfilename useg77.info
15 @c @setfilename portg77.info
16 @c To produce the full manual, use the "g77.info" setfilename, and
17 @c make sure the following do NOT begin with '@c' (and the @clear lines DO)
20 @c To produce a user-only manual, use the "useg77.info" setfilename, and
21 @c make sure the following does NOT begin with '@c':
23 @c To produce a porter-only manual, use the "portg77.info" setfilename,
24 @c and make sure the following does NOT begin with '@c':
29 @settitle Using and Porting GNU Fortran
32 @c seems reasonable to assume at least one of INTERNALS or USING is set...
34 @settitle Using GNU Fortran
37 @settitle Porting GNU Fortran
39 @c then again, have some fun
42 @settitle Doing Squat with GNU Fortran
50 @c Cause even numbered pages to be printed on the left hand side of
51 @c the page and odd numbered pages to be printed on the right hand
52 @c side of the page. Using this, you can print on both sides of a
53 @c sheet of paper and have the text on the same part of the sheet.
55 @c The text on right hand pages is pushed towards the right hand
56 @c margin and the text on left hand pages is pushed toward the left
58 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
61 @c \global\bindingoffset=0.75in
62 @c \global\normaloffset =0.75in
66 Copyright @copyright{} @value{copyrights-g77} Free Software Foundation, Inc.
68 Permission is granted to copy, distribute and/or modify this document
69 under the terms of the GNU Free Documentation License, Version 1.2 or
70 any later version published by the Free Software Foundation; with the
71 Invariant Sections being ``GNU General Public License'' and ``Funding
72 Free Software'', the Front-Cover
73 texts being (a) (see below), and with the Back-Cover Texts being (b)
74 (see below). A copy of the license is included in the section entitled
75 ``GNU Free Documentation License''.
77 (a) The FSF's Front-Cover Text is:
81 (b) The FSF's Back-Cover Text is:
83 You have freedom to copy and modify this GNU Manual, like GNU
84 software. Copies published by the Free Software Foundation raise
85 funds for GNU development.
89 @dircategory Programming
91 * g77: (g77). The GNU Fortran compiler.
95 This file documents the use and the internals of the GNU Fortran (@command{g77})
97 It corresponds to the @value{which-g77} version of @command{g77}.
101 This file documents the internals of the GNU Fortran (@command{g77}) compiler.
102 It corresponds to the @value{which-g77} version of @command{g77}.
105 This file documents the use of the GNU Fortran (@command{g77}) compiler.
106 It corresponds to the @value{which-g77} version of @command{g77}.
109 Published by the Free Software Foundation
110 59 Temple Place - Suite 330
111 Boston, MA 02111-1307 USA
116 Contributed by James Craig Burley (@email{@value{email-burley}}).
117 Inspired by a first pass at translating @file{g77-0.5.16/f/DOC} that
118 was contributed to Craig by David Ronis (@email{ronis@@onsager.chem.mcgill.ca}).
120 @setchapternewpage odd
124 @center @titlefont{Using and Porting GNU Fortran}
129 @title Using GNU Fortran
132 @title Porting GNU Fortran
135 @center James Craig Burley
137 @center Last updated @value{last-update}
139 @center for version @value{which-g77}
141 @vskip 0pt plus 1filll
142 For the @value{which-g77} Version*
144 Published by the Free Software Foundation @*
145 59 Temple Place - Suite 330@*
146 Boston, MA 02111-1307, USA@*
147 @c Last printed ??ber, 19??.@*
148 @c Printed copies are available for $? each.@*
157 @node Top, Copying,, (DIR)
163 This manual documents how to run, install and port @command{g77},
164 as well as its new features and incompatibilities,
165 and how to report bugs.
166 It corresponds to the @value{which-g77} version of @command{g77}.
171 This manual documents how to run and install @command{g77},
172 as well as its new features and incompatibilities, and how to report
174 It corresponds to the @value{which-g77} version of @command{g77}.
177 This manual documents how to port @command{g77},
178 as well as its new features and incompatibilities,
179 and how to report bugs.
180 It corresponds to the @value{which-g77} version of @command{g77}.
184 @emph{Warning:} This document is still under development,
185 and might not accurately reflect the @command{g77} code base
186 of which it is a part.
187 Efforts are made to keep it somewhat up-to-date,
188 but they are particularly concentrated
189 on any version of this information
190 that is distributed as part of a @emph{released} @command{g77}.
192 In particular, while this document is intended to apply to
193 the @value{which-g77} version of @command{g77},
194 only an official @emph{release} of that version
195 is expected to contain documentation that is
196 most consistent with the @command{g77} product in that version.
200 * Copying:: GNU General Public License says
201 how you can copy and share GNU Fortran.
202 * GNU Free Documentation License::
203 How you can copy and share this manual.
204 * Contributors:: People who have contributed to GNU Fortran.
205 * Funding:: How to help assure continued work for free software.
206 * Funding GNU Fortran:: How to help assure continued work on GNU Fortran.
208 * Getting Started:: Finding your way around this manual.
209 * What is GNU Fortran?:: How @command{g77} fits into the universe.
210 * G77 and GCC:: You can compile Fortran, C, or other programs.
211 * Invoking G77:: Command options supported by @command{g77}.
212 * News:: News about recent releases of @command{g77}.
213 * Changes:: User-visible changes to recent releases of @command{g77}.
214 * Language:: The GNU Fortran language.
215 * Compiler:: The GNU Fortran compiler.
216 * Other Dialects:: Dialects of Fortran supported by @command{g77}.
217 * Other Compilers:: Fortran compilers other than @command{g77}.
218 * Other Languages:: Languages other than Fortran.
219 * Debugging and Interfacing:: How @command{g77} generates code.
220 * Collected Fortran Wisdom:: How to avoid Trouble.
221 * Trouble:: If you have trouble with GNU Fortran.
222 * Open Questions:: Things we'd like to know.
223 * Bugs:: How, why, and where to report bugs.
224 * Service:: How to find suppliers of support for GNU Fortran.
227 * Adding Options:: Guidance on teaching @command{g77} about new options.
228 * Projects:: Projects for @command{g77} internals hackers.
229 * Front End:: Design and implementation of the @command{g77} front end.
232 * M: Diagnostics. Diagnostics produced by @command{g77}.
234 * Keyword Index:: Index of concepts and symbol names.
236 @c yes, the "M: " @emph{is} intentional -- bad.def references it (CMPAMBIG)!
243 @unnumbered Contributors to GNU Fortran
247 In addition to James Craig Burley, who wrote the front end,
248 many people have helped create and improve GNU Fortran.
252 The packaging and compiler portions of GNU Fortran are based largely
254 @xref{Contributors,,Contributors to GCC,gcc,Using the GNU Compiler
256 for more information.
259 The run-time library used by GNU Fortran is a repackaged version
260 of the @code{libf2c} library (combined from the @code{libF77} and
261 @code{libI77} libraries) provided as part of @command{f2c}, available for
262 free from @code{netlib} sites on the Internet.
265 Cygnus Support and The Free Software Foundation contributed
266 significant money and/or equipment to Craig's efforts.
269 The following individuals served as alpha testers prior to @command{g77}'s
270 public release. This work consisted of testing, researching, sometimes
271 debugging, and occasionally providing small amounts of code and fixes
272 for @command{g77}, plus offering plenty of helpful advice to Craig:
278 Dr.@: Mark Fernyhough
280 Takafumi Hayashi (The University of Aizu)---@email{takafumi@@u-aizu.ac.jp}
284 Michel Kern (INRIA and Rice University)---@email{Michel.Kern@@inria.fr}
286 Dr.@: A. O. V. Le Blanc
308 Dave Love (@email{d.love@@dl.ac.uk})
309 wrote the libU77 part of the run-time library.
312 Scott Snyder (@email{snyder@@d0sgif.fnal.gov})
313 provided the patch to add rudimentary support
314 for @code{INTEGER*1}, @code{INTEGER*2}, and
316 This inspired Craig to add further support,
317 even though the resulting support
318 would still be incomplete.
319 This support is believed to be completed at version 3.4
320 of @command{gcc} by Roger Sayle (@email{roger@@eyesopen.com}).
323 David Ronis (@email{ronis@@onsager.chem.mcgill.ca}) inspired
324 and encouraged Craig to rewrite the documentation in texinfo
325 format by contributing a first pass at a translation of the
326 old @file{g77-0.5.16/f/DOC} file.
329 Toon Moene (@email{toon@@moene.indiv.nluug.nl}) performed
330 some analysis of generated code as part of an overall project
331 to improve @command{g77} code generation to at least be as good
332 as @command{f2c} used in conjunction with @command{gcc}.
333 So far, this has resulted in the three, somewhat
334 experimental, options added by @command{g77} to the @command{gcc}
335 compiler and its back end.
337 (These, in turn, had made their way into the @code{egcs}
338 version of the compiler, and do not exist in @command{gcc}
339 version 2.8 or versions of @command{g77} based on that version
343 John Carr (@email{jfc@@mit.edu}) wrote the alias analysis improvements.
346 Thanks to Mary Cortani and the staff at Craftwork Solutions
347 (@email{support@@craftwork.com}) for all of their support.
350 Many other individuals have helped debug, test, and improve @command{g77}
351 over the past several years, and undoubtedly more people
352 will be doing so in the future.
353 If you have done so, and would like
354 to see your name listed in the above list, please ask!
355 The default is that people wish to remain anonymous.
358 @include funding.texi
360 @node Funding GNU Fortran
361 @chapter Funding GNU Fortran
362 @cindex funding improvements
363 @cindex improvements, funding
365 James Craig Burley (@email{@value{email-burley}}), the original author
366 of @command{g77}, stopped working on it in September 1999
367 (He has a web page at @uref{@value{www-burley}}.)
369 GNU Fortran is currently maintained by Toon Moene
370 (@email{toon@@moene.indiv.nluug.nl}), with the help of countless other
373 As with other GNU software, funding is important because it can pay for
374 needed equipment, personnel, and so on.
376 @cindex FSF, funding the
377 @cindex funding the FSF
378 The FSF provides information on the best way to fund ongoing
379 development of GNU software (such as GNU Fortran) in documents
380 such as the ``GNUS Bulletin''.
381 Email @email{gnu@@gnu.org} for information on funding the FSF.
383 Another important way to support work on GNU Fortran is to volunteer
386 Email @email{@value{email-general}} to volunteer for this work.
388 However, we strongly expect that there will never be a version 0.6
389 of @command{g77}. Work on this compiler has stopped as of the release
390 of GCC 3.1, except for bug fixing. @command{g77} will be succeeded by
391 @command{g95} - see @uref{http://g95.sourceforge.net}.
393 @xref{Funding,,Funding Free Software}, for more information.
395 @node Getting Started
396 @chapter Getting Started
397 @cindex getting started
402 If you don't need help getting started reading the portions
403 of this manual that are most important to you, you should skip
404 this portion of the manual.
406 If you are new to compilers, especially Fortran compilers, or
407 new to how compilers are structured under UNIX and UNIX-like
408 systems, you'll want to see @ref{What is GNU Fortran?}.
410 If you are new to GNU compilers, or have used only one GNU
411 compiler in the past and not had to delve into how it lets
412 you manage various versions and configurations of @command{gcc},
413 you should see @ref{G77 and GCC}.
415 Everyone except experienced @command{g77} users should
416 see @ref{Invoking G77}.
418 If you're acquainted with previous versions of @command{g77},
419 you should see @ref{News,,News About GNU Fortran}.
420 Further, if you've actually used previous versions of @command{g77},
421 especially if you've written or modified Fortran code to
422 be compiled by previous versions of @command{g77}, you
423 should see @ref{Changes}.
425 If you intend to write or otherwise compile code that is
426 not already strictly conforming ANSI FORTRAN 77---and this
427 is probably everyone---you should see @ref{Language}.
429 If you run into trouble getting Fortran code to compile,
430 link, run, or work properly, you might find answers
431 if you see @ref{Debugging and Interfacing},
432 see @ref{Collected Fortran Wisdom},
433 and see @ref{Trouble}.
434 You might also find that the problems you are encountering
435 are bugs in @command{g77}---see @ref{Bugs}, for information on
436 reporting them, after reading the other material.
438 If you need further help with @command{g77}, or with
439 freely redistributable software in general,
442 If you would like to help the @command{g77} project,
443 see @ref{Funding GNU Fortran}, for information on
444 helping financially, and see @ref{Projects}, for information
445 on helping in other ways.
447 If you're generally curious about the future of
448 @command{g77}, see @ref{Projects}.
449 If you're curious about its past,
450 see @ref{Contributors},
451 and see @ref{Funding GNU Fortran}.
453 To see a few of the questions maintainers of @command{g77} have,
454 and that you might be able to answer,
455 see @ref{Open Questions}.
458 @node What is GNU Fortran?
459 @chapter What is GNU Fortran?
460 @cindex concepts, basic
461 @cindex basic concepts
463 GNU Fortran, or @command{g77}, is designed initially as a free replacement
464 for, or alternative to, the UNIX @command{f77} command.
465 (Similarly, @command{gcc} is designed as a replacement
466 for the UNIX @command{cc} command.)
468 @command{g77} also is designed to fit in well with the other
469 fine GNU compilers and tools.
471 Sometimes these design goals conflict---in such cases, resolution
472 often is made in favor of fitting in well with Project GNU.
473 These cases are usually identified in the appropriate
474 sections of this manual.
477 As compilers, @command{g77}, @command{gcc}, and @command{f77}
478 share the following characteristics:
486 They read a user's program, stored in a file and
487 containing instructions written in the appropriate
488 language (Fortran, C, and so on).
489 This file contains @dfn{source code}.
491 @cindex translation of user programs
493 @cindex code, machine
496 They translate the user's program into instructions
497 a computer can carry out more quickly than it takes
498 to translate the instructions in the first place.
499 These instructions are called @dfn{machine code}---code
500 designed to be efficiently translated and processed
501 by a machine such as a computer.
502 Humans usually aren't as good writing machine code
503 as they are at writing Fortran or C, because
504 it is easy to make tiny mistakes writing machine code.
505 When writing Fortran or C, it is easy
506 to make big mistakes.
509 @cindex bugs, finding
510 @cindex @command{gdb}, command
511 @cindex commands, @command{gdb}
513 They provide information in the generated machine code
514 that can make it easier to find bugs in the program
515 (using a debugging tool, called a @dfn{debugger},
516 such as @command{gdb}).
520 @cindex @command{ld} command
521 @cindex commands, @command{ld}
523 They locate and gather machine code already generated
524 to perform actions requested by statements in
526 This machine code is organized
527 into @dfn{libraries} and is located and gathered
528 during the @dfn{link} phase of the compilation
530 (Linking often is thought of as a separate
531 step, because it can be directly invoked via the
532 @command{ld} command.
533 However, the @command{g77} and @command{gcc}
534 commands, as with most compiler commands, automatically
535 perform the linking step by calling on @command{ld}
536 directly, unless asked to not do so by the user.)
538 @cindex language, incorrect use of
539 @cindex incorrect use of language
541 They attempt to diagnose cases where the user's
542 program contains incorrect usages of the language.
543 The @dfn{diagnostics} produced by the compiler
544 indicate the problem and the location in the user's
545 source file where the problem was first noticed.
546 The user can use this information to locate and
548 @cindex diagnostics, incorrect
549 @cindex incorrect diagnostics
550 @cindex error messages, incorrect
551 @cindex incorrect error messages
552 (Sometimes an incorrect usage
553 of the language leads to a situation where the
554 compiler can no longer make any sense of what
555 follows---while a human might be able to---and
556 thus ends up complaining about many ``problems''
557 it encounters that, in fact, stem from just one
558 problem, usually the first one reported.)
561 @cindex questionable instructions
563 They attempt to diagnose cases where the user's
564 program contains a correct usage of the language,
565 but instructs the computer to do something questionable.
566 These diagnostics often are in the form of @dfn{warnings},
567 instead of the @dfn{errors} that indicate incorrect
568 usage of the language.
571 How these actions are performed is generally under the
573 Using command-line options, the user can specify
574 how persnickety the compiler is to be regarding
575 the program (whether to diagnose questionable usage
576 of the language), how much time to spend making
577 the generated machine code run faster, and so on.
579 @cindex components of @command{g77}
580 @cindex @command{g77}, components of
581 @command{g77} consists of several components:
583 @cindex @command{gcc}, command
584 @cindex commands, @command{gcc}
587 A modified version of the @command{gcc} command, which also might be
588 installed as the system's @command{cc} command.
589 (In many cases, @command{cc} refers to the
590 system's ``native'' C compiler, which
591 might be a non-GNU compiler, or an older version
592 of @command{gcc} considered more stable or that is
593 used to build the operating system kernel.)
595 @cindex @command{g77}, command
596 @cindex commands, @command{g77}
598 The @command{g77} command itself, which also might be installed as the
599 system's @command{f77} command.
601 @cindex libg2c library
602 @cindex libf2c library
603 @cindex libraries, libf2c
604 @cindex libraries, libg2c
605 @cindex run-time, library
607 The @code{libg2c} run-time library.
608 This library contains the machine code needed to support
609 capabilities of the Fortran language that are not directly
610 provided by the machine code generated by the @command{g77}
613 @code{libg2c} is just the unique name @command{g77} gives
614 to its version of @code{libf2c} to distinguish it from
615 any copy of @code{libf2c} installed from @command{f2c}
616 (or versions of @command{g77} that built @code{libf2c} under
620 The maintainer of @code{libf2c} currently is
621 @email{dmg@@bell-labs.com}.
623 @cindex @code{f771}, program
624 @cindex programs, @code{f771}
626 @cindex @command{as} command
627 @cindex commands, @command{as}
628 @cindex assembly code
629 @cindex code, assembly
631 The compiler itself, internally named @code{f771}.
633 Note that @code{f771} does not generate machine code directly---it
634 generates @dfn{assembly code} that is a more readable form
635 of machine code, leaving the conversion to actual machine code
636 to an @dfn{assembler}, usually named @command{as}.
639 @command{gcc} is often thought of as ``the C compiler'' only,
640 but it does more than that.
641 Based on command-line options and the names given for files
642 on the command line, @command{gcc} determines which actions to perform, including
643 preprocessing, compiling (in a variety of possible languages), assembling,
646 @cindex driver, gcc command as
647 @cindex @command{gcc}, command as driver
648 @cindex executable file
649 @cindex files, executable
651 @cindex programs, cc1
654 @cindex programs, cpp
655 For example, the command @samp{gcc foo.c} @dfn{drives} the file
656 @file{foo.c} through the preprocessor @command{cpp}, then
657 the C compiler (internally named
658 @code{cc1}), then the assembler (usually @command{as}), then the linker
659 (@command{ld}), producing an executable program named @file{a.out} (on
662 @cindex cc1plus program
663 @cindex programs, cc1plus
664 As another example, the command @samp{gcc foo.cc} would do much the same as
665 @samp{gcc foo.c}, but instead of using the C compiler named @code{cc1},
666 @command{gcc} would use the C++ compiler (named @code{cc1plus}).
668 @cindex @code{f771}, program
669 @cindex programs, @code{f771}
670 In a GNU Fortran installation, @command{gcc} recognizes Fortran source
671 files by name just like it does C and C++ source files.
672 It knows to use the Fortran compiler named @code{f771}, instead of
673 @code{cc1} or @code{cc1plus}, to compile Fortran files.
675 @cindex @command{gcc}, not recognizing Fortran source
676 @cindex unrecognized file format
677 @cindex file format not recognized
678 Non-Fortran-related operation of @command{gcc} is generally
679 unaffected by installing the GNU Fortran version of @command{gcc}.
680 However, without the installed version of @command{gcc} being the
681 GNU Fortran version, @command{gcc} will not be able to compile
682 and link Fortran programs---and since @command{g77} uses @command{gcc}
683 to do most of the actual work, neither will @command{g77}!
685 @cindex @command{g77}, command
686 @cindex commands, @command{g77}
687 The @command{g77} command is essentially just a front-end for
688 the @command{gcc} command.
689 Fortran users will normally use @command{g77} instead of @command{gcc},
690 because @command{g77}
691 knows how to specify the libraries needed to link with Fortran programs
692 (@code{libg2c} and @code{lm}).
693 @command{g77} can still compile and link programs and
694 source files written in other languages, just like @command{gcc}.
696 @cindex printing version information
697 @cindex version information, printing
698 The command @samp{g77 -v} is a quick
699 way to display lots of version information for the various programs
700 used to compile a typical preprocessed Fortran source file---this
701 produces much more output than @samp{gcc -v} currently does.
702 (If it produces an error message near the end of the output---diagnostics
703 from the linker, usually @command{ld}---you might
704 have an out-of-date @code{libf2c} that improperly handles
706 In the output of this command, the line beginning @samp{GNU Fortran Front
707 End} identifies the version number of GNU Fortran; immediately
708 preceding that line is a line identifying the version of @command{gcc}
709 with which that version of @command{g77} was built.
711 @cindex libf2c library
712 @cindex libraries, libf2c
713 The @code{libf2c} library is distributed with GNU Fortran for
714 the convenience of its users, but is not part of GNU Fortran.
715 It contains the procedures
716 needed by Fortran programs while they are running.
719 @cindex code, in-line
720 For example, while code generated by @command{g77} is likely
721 to do additions, subtractions, and multiplications @dfn{in line}---in
722 the actual compiled code---it is not likely to do trigonometric
725 Instead, operations like trigonometric
726 functions are compiled by the @code{f771} compiler
727 (invoked by @command{g77} when compiling Fortran code) into machine
728 code that, when run, calls on functions in @code{libg2c}, so
729 @code{libg2c} must be linked with almost every useful program
730 having any component compiled by GNU Fortran.
731 (As mentioned above, the @command{g77} command takes
732 care of all this for you.)
734 The @code{f771} program represents most of what is unique to GNU Fortran.
735 While much of the @code{libg2c} component comes from
736 the @code{libf2c} component of @command{f2c},
737 a free Fortran-to-C converter distributed by Bellcore (AT&T),
738 plus @code{libU77}, provided by Dave Love,
739 and the @command{g77} command is just a small front-end to @command{gcc},
740 @code{f771} is a combination of two rather
741 large chunks of code.
743 @cindex GNU Back End (GBE)
745 @cindex @command{gcc}, back end
746 @cindex back end, gcc
747 @cindex code generator
748 One chunk is the so-called @dfn{GNU Back End}, or GBE,
749 which knows how to generate fast code for a wide variety of processors.
750 The same GBE is used by the C, C++, and Fortran compiler programs @code{cc1},
751 @code{cc1plus}, and @code{f771}, plus others.
752 Often the GBE is referred to as the ``gcc back end'' or
753 even just ``gcc''---in this manual, the term GBE is used
754 whenever the distinction is important.
756 @cindex GNU Fortran Front End (FFE)
758 @cindex @command{g77}, front end
759 @cindex front end, @command{g77}
760 The other chunk of @code{f771} is the
761 majority of what is unique about GNU Fortran---the code that knows how
762 to interpret Fortran programs to determine what they are intending to
763 do, and then communicate that knowledge to the GBE for actual compilation
765 This chunk is called the @dfn{Fortran Front End} (FFE).
766 The @code{cc1} and @code{cc1plus} programs have their own front ends,
767 for the C and C++ languages, respectively.
768 These fronts ends are responsible for diagnosing
769 incorrect usage of their respective languages by the
770 programs the process, and are responsible for most of
771 the warnings about questionable constructs as well.
772 (The GBE handles producing some warnings, like those
773 concerning possible references to undefined variables.)
775 Because so much is shared among the compilers for various languages,
776 much of the behavior and many of the user-selectable options for these
777 compilers are similar.
778 For example, diagnostics (error messages and
779 warnings) are similar in appearance; command-line
780 options like @option{-Wall} have generally similar effects; and the quality
781 of generated code (in terms of speed and size) is roughly similar
782 (since that work is done by the shared GBE).
785 @chapter Compile Fortran, C, or Other Programs
786 @cindex compiling programs
787 @cindex programs, compiling
789 @cindex @command{gcc}, command
790 @cindex commands, @command{gcc}
791 A GNU Fortran installation includes a modified version of the @command{gcc}
794 In a non-Fortran installation, @command{gcc} recognizes C, C++,
795 and Objective-C source files.
797 In a GNU Fortran installation, @command{gcc} also recognizes Fortran source
798 files and accepts Fortran-specific command-line options, plus some
799 command-line options that are designed to cater to Fortran users
800 but apply to other languages as well.
802 @xref{G++ and GCC,,Programming Languages Supported by GCC,gcc,Using
803 the GNU Compiler Collection (GCC)},
804 for information on the way different languages are handled
805 by the GCC compiler (@command{gcc}).
807 @cindex @command{g77}, command
808 @cindex commands, @command{g77}
809 Also provided as part of GNU Fortran is the @command{g77} command.
810 The @command{g77} command is designed to make compiling and linking Fortran
811 programs somewhat easier than when using the @command{gcc} command for
813 It does this by analyzing the command line somewhat and changing it
814 appropriately before submitting it to the @command{gcc} command.
817 @cindex @command{g77} options, -v
819 Use the @option{-v} option with @command{g77}
820 to see what is going on---the first line of output is the invocation
821 of the @command{gcc} command.
832 @chapter The GNU Fortran Language
834 @cindex standard, ANSI FORTRAN 77
835 @cindex ANSI FORTRAN 77 standard
836 @cindex reference works
837 GNU Fortran supports a variety of extensions to, and dialects
838 of, the Fortran language.
839 Its primary base is the ANSI FORTRAN 77 standard, currently available on
841 @uref{http://www.fortran.com/fortran/F77_std/rjcnf0001.html}
842 or as monolithic text at
843 @uref{http://www.fortran.com/fortran/F77_std/f77_std.html}.
844 It offers some extensions that are popular among users
845 of UNIX @command{f77} and @command{f2c} compilers, some that
846 are popular among users of other compilers (such as Digital
847 products), some that are popular among users of the
848 newer Fortran 90 standard, and some that are introduced
852 (If you need a text on Fortran,
853 a few freely available electronic references have pointers from
854 @uref{http://www.fortran.com/F/books.html}. There is a `cooperative
855 net project', @cite{User Notes on Fortran Programming} at
856 @uref{ftp://vms.huji.ac.il/fortran/} and mirrors elsewhere; some of this
857 material might not apply specifically to @command{g77}.)
859 Part of what defines a particular implementation of a Fortran
860 system, such as @command{g77}, is the particular characteristics
861 of how it supports types, constants, and so on.
862 Much of this is left up to the implementation by the various
863 Fortran standards and accepted practice in the industry.
865 The GNU Fortran @emph{language} is described below.
866 Much of the material is organized along the same lines
867 as the ANSI FORTRAN 77 standard itself.
869 @xref{Other Dialects}, for information on features @command{g77} supports
870 that are not part of the GNU Fortran language.
872 @emph{Note}: This portion of the documentation definitely needs a lot
876 Relationship to the ANSI FORTRAN 77 standard:
877 * Direction of Language Development:: Where GNU Fortran is headed.
878 * Standard Support:: Degree of support for the standard.
880 Extensions to the ANSI FORTRAN 77 standard:
883 * Terms and Concepts::
884 * Characters Lines Sequence::
885 * Data Types and Constants::
887 * Specification Statements::
888 * Control Statements::
889 * Functions and Subroutines::
890 * Scope and Classes of Names::
892 * Fortran 90 Features::
895 @node Direction of Language Development
896 @section Direction of Language Development
897 @cindex direction of language development
898 @cindex features, language
899 @cindex language, features
901 The purpose of the following description of the GNU Fortran
902 language is to promote wide portability of GNU Fortran programs.
904 GNU Fortran is an evolving language, due to the
905 fact that @command{g77} itself is in beta test.
906 Some current features of the language might later
907 be redefined as dialects of Fortran supported by @command{g77}
908 when better ways to express these features are added to @command{g77},
910 Such features would still be supported by
911 @command{g77}, but would be available only when
912 one or more command-line options were used.
914 The GNU Fortran @emph{language} is distinct from the
915 GNU Fortran @emph{compilation system} (@command{g77}).
917 For example, @command{g77} supports various dialects of
918 Fortran---in a sense, these are languages other than
919 GNU Fortran---though its primary
920 purpose is to support the GNU Fortran language, which also is
921 described in its documentation and by its implementation.
923 On the other hand, non-GNU compilers might offer
924 support for the GNU Fortran language, and are encouraged
927 Currently, the GNU Fortran language is a fairly fuzzy object.
928 It represents something of a cross between what @command{g77} accepts
929 when compiling using the prevailing defaults and what this
930 document describes as being part of the language.
932 Future versions of @command{g77} are expected to clarify the
933 definition of the language in the documentation.
934 Often, this will mean adding new features to the language, in the form
935 of both new documentation and new support in @command{g77}.
936 However, it might occasionally mean removing a feature
937 from the language itself to ``dialect'' status.
938 In such a case, the documentation would be adjusted
939 to reflect the change, and @command{g77} itself would likely be changed
940 to require one or more command-line options to continue supporting
943 The development of the GNU Fortran language is intended to strike
948 Serving as a mostly-upwards-compatible language from the
949 de facto UNIX Fortran dialect as supported by @command{f77}.
952 Offering new, well-designed language features.
953 Attributes of such features include
954 not making existing code any harder to read
955 (for those who might be unaware that the new
956 features are not in use) and
957 not making state-of-the-art
958 compilers take longer to issue diagnostics,
962 Supporting existing, well-written code without gratuitously
963 rejecting non-standard constructs, regardless of the origin
964 of the code (its dialect).
967 Offering default behavior and command-line options to reduce
968 and, where reasonable, eliminate the need for programmers to make
969 any modifications to code that already works in existing
970 production environments.
973 Diagnosing constructs that have different meanings in different
974 systems, languages, and dialects, while offering clear,
975 less ambiguous ways to express each of the different meanings
976 so programmers can change their code appropriately.
979 One of the biggest practical challenges for the developers of the
980 GNU Fortran language is meeting the sometimes contradictory demands
983 For example, a feature might be widely used in one popular environment,
984 but the exact same code that utilizes that feature might not work
985 as expected---perhaps it might mean something entirely different---in
986 another popular environment.
988 Traditionally, Fortran compilers---even portable ones---have solved this
989 problem by simply offering the appropriate feature to users of
990 the respective systems.
991 This approach treats users of various Fortran systems and dialects
992 as remote ``islands'', or camps, of programmers, and assume that these
993 camps rarely come into contact with each other (or,
994 especially, with each other's code).
996 Project GNU takes a radically different approach to software and language
997 design, in that it assumes that users of GNU software do not necessarily
998 care what kind of underlying system they are using, regardless
999 of whether they are using software (at the user-interface
1000 level) or writing it (for example, writing Fortran or C code).
1002 As such, GNU users rarely need consider just what kind of underlying
1003 hardware (or, in many cases, operating system) they are using at any
1005 They can use and write software designed for a general-purpose,
1006 widely portable, heterogeneous environment---the GNU environment.
1008 In line with this philosophy, GNU Fortran must evolve into a product
1009 that is widely ported and portable not only in the sense that it can
1010 be successfully built, installed, and run by users, but in the larger
1011 sense that its users can use it in the same way, and expect largely the
1012 same behaviors from it, regardless of the kind of system they are using
1013 at any particular time.
1015 This approach constrains the solutions @command{g77} can use to resolve
1016 conflicts between various camps of Fortran users.
1017 If these two camps disagree about what a particular construct should
1018 mean, @command{g77} cannot simply be changed to treat that particular construct as
1019 having one meaning without comment (such as a warning), lest the users
1020 expecting it to have the other meaning are unpleasantly surprised that
1021 their code misbehaves when executed.
1023 The use of the ASCII backslash character in character constants is
1024 an excellent (and still somewhat unresolved) example of this kind of
1026 @xref{Backslash in Constants}.
1027 Other examples are likely to arise in the future, as @command{g77} developers
1028 strive to improve its ability to accept an ever-wider variety of existing
1029 Fortran code without requiring significant modifications to said code.
1031 Development of GNU Fortran is further constrained by the desire
1032 to avoid requiring programmers to change their code.
1033 This is important because it allows programmers, administrators,
1034 and others to more faithfully evaluate and validate @command{g77}
1035 (as an overall product and as new versions are distributed)
1036 without having to support multiple versions of their programs
1037 so that they continue to work the same way on their existing
1038 systems (non-GNU perhaps, but possibly also earlier versions
1041 @node Standard Support
1042 @section ANSI FORTRAN 77 Standard Support
1043 @cindex ANSI FORTRAN 77 support
1044 @cindex standard, support for
1045 @cindex support, FORTRAN 77
1046 @cindex compatibility, FORTRAN 77
1047 @cindex FORTRAN 77 compatibility
1049 GNU Fortran supports ANSI FORTRAN 77 with the following caveats.
1050 In summary, the only ANSI FORTRAN 77 features @command{g77} doesn't
1051 support are those that are probably rarely used in actual code,
1052 some of which are explicitly disallowed by the Fortran 90 standard.
1055 * No Passing External Assumed-length:: CHAR*(*) CFUNC restriction.
1056 * No Passing Dummy Assumed-length:: CHAR*(*) CFUNC restriction.
1057 * No Pathological Implied-DO:: No @samp{((@dots{}, I=@dots{}), I=@dots{})}.
1058 * No Useless Implied-DO:: No @samp{(A, I=1, 1)}.
1061 @node No Passing External Assumed-length
1062 @subsection No Passing External Assumed-length
1064 @command{g77} disallows passing of an external procedure
1065 as an actual argument if the procedure's
1066 type is declared @code{CHARACTER*(*)}. For example:
1076 It isn't clear whether the standard considers this conforming.
1078 @node No Passing Dummy Assumed-length
1079 @subsection No Passing Dummy Assumed-length
1081 @command{g77} disallows passing of a dummy procedure
1082 as an actual argument if the procedure's
1083 type is declared @code{CHARACTER*(*)}.
1086 SUBROUTINE BAR(CFUNC)
1094 It isn't clear whether the standard considers this conforming.
1096 @node No Pathological Implied-DO
1097 @subsection No Pathological Implied-DO
1099 The @code{DO} variable for an implied-@code{DO} construct in a
1100 @code{DATA} statement may not be used as the @code{DO} variable
1101 for an outer implied-@code{DO} construct. For example, this
1102 fragment is disallowed by @command{g77}:
1105 DATA ((A(I, I), I= 1, 10), I= 1, 10) /@dots{}/
1109 This also is disallowed by Fortran 90, as it offers no additional
1110 capabilities and would have a variety of possible meanings.
1112 Note that it is @emph{very} unlikely that any production Fortran code
1113 tries to use this unsupported construct.
1115 @node No Useless Implied-DO
1116 @subsection No Useless Implied-DO
1118 An array element initializer in an implied-@code{DO} construct in a
1119 @code{DATA} statement must contain at least one reference to the @code{DO}
1120 variables of each outer implied-@code{DO} construct. For example,
1121 this fragment is disallowed by @command{g77}:
1124 DATA (A, I= 1, 1) /1./
1128 This also is disallowed by Fortran 90, as FORTRAN 77's more permissive
1129 requirements offer no additional capabilities.
1130 However, @command{g77} doesn't necessarily diagnose all cases
1131 where this requirement is not met.
1133 Note that it is @emph{very} unlikely that any production Fortran code
1134 tries to use this unsupported construct.
1137 @section Conformance
1139 (The following information augments or overrides the information in
1140 Section 1.4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
1142 Chapter 1 of that document otherwise serves as the basis
1143 for the relevant aspects of GNU Fortran.)
1145 The definition of the GNU Fortran language is akin to that of
1146 the ANSI FORTRAN 77 language in that it does not generally require
1147 conforming implementations to diagnose cases where programs do
1148 not conform to the language.
1150 However, @command{g77} as a compiler is being developed in a way that
1151 is intended to enable it to diagnose such cases in an easy-to-understand
1154 A program that conforms to the GNU Fortran language should, when
1155 compiled, linked, and executed using a properly installed @command{g77}
1156 system, perform as described by the GNU Fortran language definition.
1157 Reasons for different behavior include, among others:
1161 Use of resources (memory---heap, stack, and so on; disk space; CPU
1162 time; etc.) exceeds those of the system.
1165 Range and/or precision of calculations required by the program
1166 exceeds that of the system.
1169 Excessive reliance on behaviors that are system-dependent
1170 (non-portable Fortran code).
1173 Bugs in the program.
1176 Bug in @command{g77}.
1182 Despite these ``loopholes'', the availability of a clear specification
1183 of the language of programs submitted to @command{g77}, as this document
1184 is intended to provide, is considered an important aspect of providing
1185 a robust, clean, predictable Fortran implementation.
1187 The definition of the GNU Fortran language, while having no special
1188 legal status, can therefore be viewed as a sort of contract, or agreement.
1189 This agreement says, in essence, ``if you write a program in this language,
1190 and run it in an environment (such as a @command{g77} system) that supports
1191 this language, the program should behave in a largely predictable way''.
1194 @section Notation Used in This Chapter
1196 (The following information augments or overrides the information in
1197 Section 1.5 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
1199 Chapter 1 of that document otherwise serves as the basis
1200 for the relevant aspects of GNU Fortran.)
1202 In this chapter, ``must'' denotes a requirement, ``may'' denotes permission,
1203 and ``must not'' and ``may not'' denote prohibition.
1204 Terms such as ``might'', ``should'', and ``can'' generally add little or
1205 nothing in the way of weight to the GNU Fortran language itself,
1206 but are used to explain or illustrate the language.
1211 ``The @code{FROBNITZ} statement must precede all executable
1212 statements in a program unit, and may not specify any dummy
1213 arguments. It may specify local or common variables and arrays.
1214 Its use should be limited to portions of the program designed to
1215 be non-portable and system-specific, because it might cause the
1216 containing program unit to behave quite differently on different
1220 Insofar as the GNU Fortran language is specified,
1221 the requirements and permissions denoted by the above sample statement
1222 are limited to the placement of the statement and the kinds of
1223 things it may specify.
1224 The rest of the statement---the content regarding non-portable portions
1225 of the program and the differing behavior of program units containing
1226 the @code{FROBNITZ} statement---does not pertain the GNU Fortran
1228 That content offers advice and warnings about the @code{FROBNITZ}
1231 @emph{Remember:} The GNU Fortran language definition specifies
1232 both what constitutes a valid GNU Fortran program and how,
1233 given such a program, a valid GNU Fortran implementation is
1234 to interpret that program.
1236 It is @emph{not} incumbent upon a valid GNU Fortran implementation
1237 to behave in any particular way, any consistent way, or any
1238 predictable way when it is asked to interpret input that is
1239 @emph{not} a valid GNU Fortran program.
1241 Such input is said to have @dfn{undefined} behavior when
1242 interpreted by a valid GNU Fortran implementation, though
1243 an implementation may choose to specify behaviors for some
1244 cases of inputs that are not valid GNU Fortran programs.
1246 Other notation used herein is that of the GNU texinfo format,
1247 which is used to generate printed hardcopy, on-line hypertext
1248 (Info), and on-line HTML versions, all from a single source
1250 This notation is used as follows:
1254 Keywords defined by the GNU Fortran language are shown
1255 in uppercase, as in: @code{COMMON}, @code{INTEGER}, and
1258 Note that, in practice, many Fortran programs are written
1259 in lowercase---uppercase is used in this manual as a
1260 means to readily distinguish keywords and sample Fortran-related
1261 text from the prose in this document.
1264 Portions of actual sample program, input, or output text
1265 look like this: @samp{Actual program text}.
1267 Generally, uppercase is used for all Fortran-specific and
1268 Fortran-related text, though this does not always include
1269 literal text within Fortran code.
1271 For example: @samp{PRINT *, 'My name is Bob'}.
1274 A metasyntactic variable---that is, a name used in this document
1275 to serve as a placeholder for whatever text is used by the
1276 user or programmer---appears as shown in the following example:
1278 ``The @code{INTEGER @var{ivar}} statement specifies that
1279 @var{ivar} is a variable or array of type @code{INTEGER}.''
1281 In the above example, any valid text may be substituted for
1282 the metasyntactic variable @var{ivar} to make the statement
1283 apply to a specific instance, as long as the same text is
1284 substituted for @emph{both} occurrences of @var{ivar}.
1287 Ellipses (``@dots{}'') are used to indicate further text that
1288 is either unimportant or expanded upon further, elsewhere.
1291 Names of data types are in the style of Fortran 90, in most
1294 @xref{Kind Notation}, for information on the relationship
1295 between Fortran 90 nomenclature (such as @code{INTEGER(KIND=1)})
1296 and the more traditional, less portably concise nomenclature
1297 (such as @code{INTEGER*4}).
1300 @node Terms and Concepts
1301 @section Fortran Terms and Concepts
1303 (The following information augments or overrides the information in
1304 Chapter 2 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
1306 Chapter 2 of that document otherwise serves as the basis
1307 for the relevant aspects of GNU Fortran.)
1311 * Statements Comments Lines::
1312 * Scope of Names and Labels::
1315 @node Syntactic Items
1316 @subsection Syntactic Items
1318 (Corresponds to Section 2.2 of ANSI X3.9-1978 FORTRAN 77.)
1320 @cindex limits, lengths of names
1321 In GNU Fortran, a symbolic name is at least one character long,
1322 and has no arbitrary upper limit on length.
1323 However, names of entities requiring external linkage (such as
1324 external functions, external subroutines, and @code{COMMON} areas)
1325 might be restricted to some arbitrary length by the system.
1326 Such a restriction is no more constrained than that of one
1327 through six characters.
1329 Underscores (@samp{_}) are accepted in symbol names after the first
1330 character (which must be a letter).
1332 @node Statements Comments Lines
1333 @subsection Statements, Comments, and Lines
1335 (Corresponds to Section 2.3 of ANSI X3.9-1978 FORTRAN 77.)
1337 @cindex trailing comment
1339 @cindex characters, comment
1341 @cindex exclamation point
1342 @cindex continuation character
1343 @cindex characters, continuation
1344 Use of an exclamation point (@samp{!}) to begin a
1345 trailing comment (a comment that extends to the end of the same
1346 source line) is permitted under the following conditions:
1350 The exclamation point does not appear in column 6.
1351 Otherwise, it is treated as an indicator of a continuation
1355 The exclamation point appears outside a character or Hollerith
1357 Otherwise, the exclamation point is considered part of the
1361 The exclamation point appears to the left of any other possible
1363 That is, a trailing comment may contain exclamation points
1364 in their commentary text.
1369 @cindex statements, separated by semicolon
1370 Use of a semicolon (@samp{;}) as a statement separator
1371 is permitted under the following conditions:
1375 The semicolon appears outside a character or Hollerith
1377 Otherwise, the semicolon is considered part of the
1381 The semicolon appears to the left of a trailing comment.
1382 Otherwise, the semicolon is considered part of that
1386 Neither a logical @code{IF} statement nor a non-construct
1387 @code{WHERE} statement (a Fortran 90 feature) may be
1388 followed (in the same, possibly continued, line) by
1389 a semicolon used as a statement separator.
1391 This restriction avoids the confusion
1392 that can result when reading a line such as:
1395 IF (VALIDP) CALL FOO; CALL BAR
1399 Some readers might think the @samp{CALL BAR} is executed
1400 only if @samp{VALIDP} is @code{.TRUE.}, while others might
1401 assume its execution is unconditional.
1403 (At present, @command{g77} does not diagnose code that
1404 violates this restriction.)
1407 @node Scope of Names and Labels
1408 @subsection Scope of Symbolic Names and Statement Labels
1411 (Corresponds to Section 2.9 of ANSI X3.9-1978 FORTRAN 77.)
1413 Included in the list of entities that have a scope of a
1414 program unit are construct names (a Fortran 90 feature).
1415 @xref{Construct Names}, for more information.
1417 @node Characters Lines Sequence
1418 @section Characters, Lines, and Execution Sequence
1420 (The following information augments or overrides the information in
1421 Chapter 3 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
1423 Chapter 3 of that document otherwise serves as the basis
1424 for the relevant aspects of GNU Fortran.)
1429 * Continuation Line::
1431 * Statement Labels::
1434 * Cpp-style directives::
1438 @subsection GNU Fortran Character Set
1441 (Corresponds to Section 3.1 of ANSI X3.9-1978 FORTRAN 77.)
1443 Letters include uppercase letters (the twenty-six characters
1444 of the English alphabet) and lowercase letters (their lowercase
1446 Generally, lowercase letters may be used in place of uppercase
1447 letters, though in character and Hollerith constants, they
1450 Special characters include:
1456 Semicolon (@samp{;})
1460 @cindex exclamation point
1461 Exclamation point (@samp{!})
1465 @cindex double quote
1466 Double quote (@samp{"})
1471 Backslash (@samp{\})
1475 @cindex question mark
1476 Question mark (@samp{?})
1482 Hash mark (@samp{#})
1487 Ampersand (@samp{&})
1491 @cindex percent sign
1492 Percent sign (@samp{%})
1497 Underscore (@samp{_})
1503 @cindex open bracket
1504 @cindex left bracket
1505 Open angle (@samp{<})
1511 @cindex close bracket
1512 @cindex right bracket
1513 Close angle (@samp{>})
1516 The FORTRAN 77 special characters (@key{SPC}, @samp{=},
1517 @samp{+}, @samp{-}, @samp{*}, @samp{/}, @samp{(},
1518 @samp{)}, @samp{,}, @samp{.}, @samp{$}, @samp{'},
1525 Note that this document refers to @key{SPC} as @dfn{space},
1526 while X3.9-1978 FORTRAN 77 refers to it as @dfn{blank}.
1531 @cindex source file format
1532 @cindex source format
1533 @cindex file, source
1535 @cindex code, source
1539 (Corresponds to Section 3.2 of ANSI X3.9-1978 FORTRAN 77.)
1541 The way a Fortran compiler views source files depends entirely on the
1542 implementation choices made for the compiler, since those choices
1543 are explicitly left to the implementation by the published Fortran
1546 The GNU Fortran language mandates a view applicable to UNIX-like
1547 text files---files that are made up of an arbitrary number of lines,
1548 each with an arbitrary number of characters (sometimes called stream-based
1551 This view does not apply to types of files that are specified as
1552 having a particular number of characters on every single line (sometimes
1553 referred to as record-based files).
1555 Because a ``line in a program unit is a sequence of 72 characters'',
1556 to quote X3.9-1978, the GNU Fortran language specifies that a
1557 stream-based text file is translated to GNU Fortran lines as follows:
1561 A newline in the file is the character that represents the end of
1562 a line of text to the underlying system.
1563 For example, on ASCII-based systems, a newline is the @key{NL}
1564 character, which has ASCII value 10 (decimal).
1567 Each newline in the file serves to end the line of text that precedes
1568 it (and that does not contain a newline).
1571 The end-of-file marker (@code{EOF}) also serves to end the line
1572 of text that precedes it (and that does not contain a newline).
1578 Any line of text that is shorter than 72 characters is padded to that length
1579 with spaces (called ``blanks'' in the standard).
1582 Any line of text that is longer than 72 characters is truncated to that
1583 length, but the truncated remainder must consist entirely of spaces.
1586 Characters other than newline and the GNU Fortran character set
1590 For the purposes of the remainder of this description of the GNU
1591 Fortran language, the translation described above has already
1592 taken place, unless otherwise specified.
1594 The result of the above translation is that the source file appears,
1595 in terms of the remainder of this description of the GNU Fortran language,
1596 as if it had an arbitrary
1597 number of 72-character lines, each character being among the GNU Fortran
1600 For example, if the source file itself has two newlines in a row,
1601 the second newline becomes, after the above translation, a single
1602 line containing 72 spaces.
1604 @node Continuation Line
1605 @subsection Continuation Line
1606 @cindex continuation line, number of
1607 @cindex lines, continuation
1608 @cindex number of continuation lines
1609 @cindex limits, continuation lines
1611 (Corresponds to Section 3.2.3 of ANSI X3.9-1978 FORTRAN 77.)
1613 A continuation line is any line that both
1617 Contains a continuation character, and
1620 Contains only spaces in columns 1 through 5
1623 A continuation character is any character of the GNU Fortran character set
1624 other than space (@key{SPC}) or zero (@samp{0})
1625 in column 6, or a digit (@samp{0} through @samp{9}) in column
1626 7 through 72 of a line that has only spaces to the left of that
1629 The continuation character is ignored as far as the content of
1630 the statement is concerned.
1632 The GNU Fortran language places no limit on the number of
1633 continuation lines in a statement.
1634 In practice, the limit depends on a variety of factors, such as
1635 available memory, statement content, and so on, but no
1636 GNU Fortran system may impose an arbitrary limit.
1639 @subsection Statements
1641 (Corresponds to Section 3.3 of ANSI X3.9-1978 FORTRAN 77.)
1643 Statements may be written using an arbitrary number of continuation
1646 Statements may be separated using the semicolon (@samp{;}), except
1647 that the logical @code{IF} and non-construct @code{WHERE} statements
1648 may not be separated from subsequent statements using only a semicolon
1649 as statement separator.
1651 The @code{END PROGRAM}, @code{END SUBROUTINE}, @code{END FUNCTION},
1652 and @code{END BLOCK DATA} statements are alternatives to the @code{END}
1654 These alternatives may be written as normal statements---they are not
1655 subject to the restrictions of the @code{END} statement.
1657 However, no statement other than @code{END} may have an initial line
1658 that appears to be an @code{END} statement---even @code{END PROGRAM},
1659 for example, must not be written as:
1666 @node Statement Labels
1667 @subsection Statement Labels
1669 (Corresponds to Section 3.4 of ANSI X3.9-1978 FORTRAN 77.)
1671 A statement separated from its predecessor via a semicolon may be
1676 The semicolon is followed by the label for the statement,
1677 which in turn follows the label.
1680 The label must be no more than five digits in length.
1683 The first digit of the label for the statement is not
1684 the first non-space character on a line.
1685 Otherwise, that character is treated as a continuation
1689 A statement may have only one label defined for it.
1692 @subsection Order of Statements and Lines
1694 (Corresponds to Section 3.5 of ANSI X3.9-1978 FORTRAN 77.)
1696 Generally, @code{DATA} statements may precede executable statements.
1697 However, specification statements pertaining to any entities
1698 initialized by a @code{DATA} statement must precede that @code{DATA}
1701 after @samp{DATA I/1/}, @samp{INTEGER I} is not permitted, but
1702 @samp{INTEGER J} is permitted.
1704 The last line of a program unit may be an @code{END} statement,
1709 An @code{END PROGRAM} statement, if the program unit is a main program.
1712 An @code{END SUBROUTINE} statement, if the program unit is a subroutine.
1715 An @code{END FUNCTION} statement, if the program unit is a function.
1718 An @code{END BLOCK DATA} statement, if the program unit is a block data.
1722 @subsection Including Source Text
1723 @cindex INCLUDE directive
1725 Additional source text may be included in the processing of
1726 the source file via the @code{INCLUDE} directive:
1729 INCLUDE @var{filename}
1733 The source text to be included is identified by @var{filename},
1734 which is a literal GNU Fortran character constant.
1735 The meaning and interpretation of @var{filename} depends on the
1736 implementation, but typically is a filename.
1738 (@command{g77} treats it as a filename that it searches for
1739 in the current directory and/or directories specified
1740 via the @option{-I} command-line option.)
1742 The effect of the @code{INCLUDE} directive is as if the
1743 included text directly replaced the directive in the source
1744 file prior to interpretation of the program.
1745 Included text may itself use @code{INCLUDE}.
1746 The depth of nested @code{INCLUDE} references depends on
1747 the implementation, but typically is a positive integer.
1749 This virtual replacement treats the statements and @code{INCLUDE}
1750 directives in the included text as syntactically distinct from
1751 those in the including text.
1753 Therefore, the first non-comment line of the included text
1754 must not be a continuation line.
1755 The included text must therefore have, after the non-comment
1756 lines, either an initial line (statement), an @code{INCLUDE}
1757 directive, or nothing (the end of the included text).
1759 Similarly, the including text may end the @code{INCLUDE}
1760 directive with a semicolon or the end of the line, but it
1761 cannot follow an @code{INCLUDE} directive at the end of its
1762 line with a continuation line.
1763 Thus, the last statement in an included text may not be
1766 Any statements between two @code{INCLUDE} directives on the
1767 same line are treated as if they appeared in between the
1768 respective included texts.
1772 INCLUDE 'A'; PRINT *, 'B'; INCLUDE 'C'; END PROGRAM
1776 If the text included by @samp{INCLUDE 'A'} constitutes
1777 a @samp{PRINT *, 'A'} statement and the text included by
1778 @samp{INCLUDE 'C'} constitutes a @samp{PRINT *, 'C'} statement,
1779 then the output of the above sample program would be
1788 (with suitable allowances for how an implementation defines
1789 its handling of output).
1791 Included text must not include itself directly or indirectly,
1792 regardless of whether the @var{filename} used to reference
1793 the text is the same.
1795 Note that @code{INCLUDE} is @emph{not} a statement.
1796 As such, it is neither a non-executable or executable
1798 However, if the text it includes constitutes one or more
1799 executable statements, then the placement of @code{INCLUDE}
1800 is subject to effectively the same restrictions as those
1801 on executable statements.
1803 An @code{INCLUDE} directive may be continued across multiple
1804 lines as if it were a statement.
1805 This permits long names to be used for @var{filename}.
1807 @node Cpp-style directives
1808 @subsection Cpp-style directives
1810 @cindex preprocessor
1812 @code{cpp} output-style @code{#} directives
1813 (@pxref{C Preprocessor Output,,, cpp, The C Preprocessor})
1814 are recognized by the compiler even
1815 when the preprocessor isn't run on the input (as it is when compiling
1816 @samp{.F} files). (Note the distinction between these @command{cpp}
1817 @code{#} @emph{output} directives and @code{#line} @emph{input}
1820 @node Data Types and Constants
1821 @section Data Types and Constants
1823 (The following information augments or overrides the information in
1824 Chapter 4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
1826 Chapter 4 of that document otherwise serves as the basis
1827 for the relevant aspects of GNU Fortran.)
1829 To more concisely express the appropriate types for
1830 entities, this document uses the more concise
1831 Fortran 90 nomenclature such as @code{INTEGER(KIND=1)}
1832 instead of the more traditional, but less portably concise,
1833 byte-size-based nomenclature such as @code{INTEGER*4},
1834 wherever reasonable.
1836 When referring to generic types---in contexts where the
1837 specific precision and range of a type are not important---this
1838 document uses the generic type names @code{INTEGER}, @code{LOGICAL},
1839 @code{REAL}, @code{COMPLEX}, and @code{CHARACTER}.
1841 In some cases, the context requires specification of a
1843 This document uses the @samp{KIND=} notation to accomplish
1844 this throughout, sometimes supplying the more traditional
1845 notation for clarification, though the traditional notation
1846 might not work the same way on all GNU Fortran implementations.
1848 Use of @samp{KIND=} makes this document more concise because
1849 @command{g77} is able to define values for @samp{KIND=} that
1850 have the same meanings on all systems, due to the way the
1851 Fortran 90 standard specifies these values are to be used.
1853 (In particular, that standard permits an implementation to
1854 arbitrarily assign nonnegative values.
1855 There are four distinct sets of assignments: one to the @code{CHARACTER}
1856 type; one to the @code{INTEGER} type; one to the @code{LOGICAL} type;
1857 and the fourth to both the @code{REAL} and @code{COMPLEX} types.
1858 Implementations are free to assign these values in any order,
1859 leave gaps in the ordering of assignments, and assign more than
1860 one value to a representation.)
1862 This makes @samp{KIND=} values superior to the values used
1863 in non-standard statements such as @samp{INTEGER*4}, because
1864 the meanings of the values in those statements vary from machine
1865 to machine, compiler to compiler, even operating system to
1868 However, use of @samp{KIND=} is @emph{not} generally recommended
1869 when writing portable code (unless, for example, the code is
1870 going to be compiled only via @command{g77}, which is a widely
1872 GNU Fortran does not yet have adequate language constructs to
1873 permit use of @samp{KIND=} in a fashion that would make the
1874 code portable to Fortran 90 implementations; and, this construct
1875 is known to @emph{not} be accepted by many popular FORTRAN 77
1876 implementations, so it cannot be used in code that is to be ported
1879 The distinction here is that this document is able to use
1880 specific values for @samp{KIND=} to concisely document the
1881 types of various operations and operands.
1883 A Fortran program should use the FORTRAN 77 designations for the
1884 appropriate GNU Fortran types---such as @code{INTEGER} for
1885 @code{INTEGER(KIND=1)}, @code{REAL} for @code{REAL(KIND=1)},
1886 and @code{DOUBLE COMPLEX} for @code{COMPLEX(KIND=2)}---and,
1887 where no such designations exist, make use of appropriate
1888 techniques (preprocessor macros, parameters, and so on)
1889 to specify the types in a fashion that may be easily adjusted
1890 to suit each particular implementation to which the program
1892 (These types generally won't need to be adjusted for ports of
1895 Further details regarding GNU Fortran data types and constants
1906 @subsection Data Types
1908 (Corresponds to Section 4.1 of ANSI X3.9-1978 FORTRAN 77.)
1910 GNU Fortran supports these types:
1914 Integer (generic type @code{INTEGER})
1917 Real (generic type @code{REAL})
1923 Complex (generic type @code{COMPLEX})
1926 Logical (generic type @code{LOGICAL})
1929 Character (generic type @code{CHARACTER})
1935 (The types numbered 1 through 6 above are standard FORTRAN 77 types.)
1937 The generic types shown above are referred to in this document
1938 using only their generic type names.
1939 Such references usually indicate that any specific type (kind)
1940 of that generic type is valid.
1942 For example, a context described in this document as accepting
1943 the @code{COMPLEX} type also is likely to accept the
1944 @code{DOUBLE COMPLEX} type.
1946 The GNU Fortran language supports three ways to specify
1947 a specific kind of a generic type.
1950 * Double Notation:: As in @code{DOUBLE COMPLEX}.
1951 * Star Notation:: As in @code{INTEGER*4}.
1952 * Kind Notation:: As in @code{INTEGER(KIND=1)}.
1955 @node Double Notation
1956 @subsubsection Double Notation
1958 The GNU Fortran language supports two uses of the keyword
1959 @code{DOUBLE} to specify a specific kind of type:
1963 @code{DOUBLE PRECISION}, equivalent to @code{REAL(KIND=2)}
1966 @code{DOUBLE COMPLEX}, equivalent to @code{COMPLEX(KIND=2)}
1969 Use one of the above forms where a type name is valid.
1971 While use of this notation is popular, it doesn't scale
1972 well in a language or dialect rich in intrinsic types,
1973 as is the case for the GNU Fortran language (especially
1974 planned future versions of it).
1976 After all, one rarely sees type names such as @samp{DOUBLE INTEGER},
1977 @samp{QUADRUPLE REAL}, or @samp{QUARTER INTEGER}.
1978 Instead, @code{INTEGER*8}, @code{REAL*16}, and @code{INTEGER*1}
1979 often are substituted for these, respectively, even though they
1980 do not always have the same meanings on all systems.
1981 (And, the fact that @samp{DOUBLE REAL} does not exist as such
1982 is an inconsistency.)
1984 Therefore, this document uses ``double notation'' only on occasion
1985 for the benefit of those readers who are accustomed to it.
1988 @subsubsection Star Notation
1989 @cindex *@var{n} notation
1991 The following notation specifies the storage size for a type:
1994 @var{generic-type}*@var{n}
1998 @var{generic-type} must be a generic type---one of
1999 @code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL},
2000 or @code{CHARACTER}.
2001 @var{n} must be one or more digits comprising a decimal
2002 integer number greater than zero.
2004 Use the above form where a type name is valid.
2006 The @samp{*@var{n}} notation specifies that the amount of storage
2007 occupied by variables and array elements of that type is @var{n}
2008 times the storage occupied by a @code{CHARACTER*1} variable.
2010 This notation might indicate a different degree of precision and/or
2011 range for such variables and array elements, and the functions that
2012 return values of types using this notation.
2013 It does not limit the precision or range of values of that type
2014 in any particular way---use explicit code to do that.
2016 Further, the GNU Fortran language requires no particular values
2017 for @var{n} to be supported by an implementation via the @samp{*@var{n}}
2019 @command{g77} supports @code{INTEGER*1} (as @code{INTEGER(KIND=3)})
2020 on all systems, for example,
2021 but not all implementations are required to do so, and @command{g77}
2022 is known to not support @code{REAL*1} on most (or all) systems.
2024 As a result, except for @var{generic-type} of @code{CHARACTER},
2025 uses of this notation should be limited to isolated
2026 portions of a program that are intended to handle system-specific
2027 tasks and are expected to be non-portable.
2029 (Standard FORTRAN 77 supports the @samp{*@var{n}} notation for
2030 only @code{CHARACTER}, where it signifies not only the amount
2031 of storage occupied, but the number of characters in entities
2033 However, almost all Fortran compilers have supported this
2034 notation for generic types, though with a variety of meanings
2037 Specifications of types using the @samp{*@var{n}} notation
2038 always are interpreted as specifications of the appropriate
2039 types described in this document using the @samp{KIND=@var{n}}
2040 notation, described below.
2042 While use of this notation is popular, it doesn't serve well
2043 in the context of a widely portable dialect of Fortran, such as
2044 the GNU Fortran language.
2046 For example, even on one particular machine, two or more popular
2047 Fortran compilers might well disagree on the size of a type
2048 declared @code{INTEGER*2} or @code{REAL*16}.
2050 is known to be disagreement over such things among Fortran
2051 compilers on @emph{different} systems.
2053 Further, this notation offers no elegant way to specify sizes
2054 that are not even multiples of the ``byte size'' typically
2055 designated by @code{INTEGER*1}.
2056 Use of ``absurd'' values (such as @code{INTEGER*1000}) would
2057 certainly be possible, but would perhaps be stretching the original
2058 intent of this notation beyond the breaking point in terms
2059 of widespread readability of documentation and code making use
2062 Therefore, this document uses ``star notation'' only on occasion
2063 for the benefit of those readers who are accustomed to it.
2066 @subsubsection Kind Notation
2067 @cindex KIND= notation
2069 The following notation specifies the kind-type selector of a type:
2072 @var{generic-type}(KIND=@var{n})
2076 Use the above form where a type name is valid.
2078 @var{generic-type} must be a generic type---one of
2079 @code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL},
2080 or @code{CHARACTER}.
2081 @var{n} must be an integer initialization expression that
2082 is a positive, nonzero value.
2084 Programmers are discouraged from writing these values directly
2086 Future versions of the GNU Fortran language will offer
2087 facilities that will make the writing of code portable
2088 to @command{g77} @emph{and} Fortran 90 implementations simpler.
2090 However, writing code that ports to existing FORTRAN 77
2091 implementations depends on avoiding the @samp{KIND=} construct.
2093 The @samp{KIND=} construct is thus useful in the context
2094 of GNU Fortran for two reasons:
2098 It provides a means to specify a type in a fashion that
2099 is portable across all GNU Fortran implementations (though
2100 not other FORTRAN 77 and Fortran 90 implementations).
2103 It provides a sort of Rosetta stone for this document to use
2104 to concisely describe the types of various operations and
2108 The values of @var{n} in the GNU Fortran language are
2109 assigned using a scheme that:
2113 Attempts to maximize the ability of readers
2114 of this document to quickly familiarize themselves
2115 with assignments for popular types
2118 Provides a unique value for each specific desired
2122 Provides a means to automatically assign new values so
2123 they have a ``natural'' relationship to existing values,
2124 if appropriate, or, if no such relationship exists, will
2125 not interfere with future values assigned on the basis
2126 of such relationships
2129 Avoids using values that are similar to values used
2130 in the existing, popular @samp{*@var{n}} notation,
2131 to prevent readers from expecting that these implied
2132 correspondences work on all GNU Fortran implementations
2135 The assignment system accomplishes this by assigning
2136 to each ``fundamental meaning'' of a specific type a
2137 unique prime number.
2138 Combinations of fundamental meanings---for example, a type
2139 that is two times the size of some other type---are assigned
2140 values of @var{n} that are the products of the values for
2141 those fundamental meanings.
2143 A prime value of @var{n} is never given more than one fundamental
2144 meaning, to avoid situations where some code or system
2145 cannot reasonably provide those meanings in the form of a
2148 The values of @var{n} assigned so far are:
2152 This value is reserved for future use.
2154 The planned future use is for this value to designate,
2155 explicitly, context-sensitive kind-type selection.
2156 For example, the expression @samp{1D0 * 0.1_0} would
2157 be equivalent to @samp{1D0 * 0.1D0}.
2160 This corresponds to the default types for
2161 @code{REAL}, @code{INTEGER}, @code{LOGICAL}, @code{COMPLEX},
2162 and @code{CHARACTER}, as appropriate.
2164 These are the ``default'' types described in the Fortran 90 standard,
2165 though that standard does not assign any particular @samp{KIND=}
2166 value to these types.
2168 (Typically, these are @code{REAL*4}, @code{INTEGER*4},
2169 @code{LOGICAL*4}, and @code{COMPLEX*8}.)
2172 This corresponds to types that occupy twice as much
2173 storage as the default types.
2174 @code{REAL(KIND=2)} is @code{DOUBLE PRECISION} (typically @code{REAL*8}),
2175 @code{COMPLEX(KIND=2)} is @code{DOUBLE COMPLEX} (typically @code{COMPLEX*16}),
2177 These are the ``double precision'' types described in the Fortran 90
2179 though that standard does not assign any particular @samp{KIND=}
2180 value to these types.
2182 @var{n} of 4 thus corresponds to types that occupy four times
2183 as much storage as the default types, @var{n} of 8 to types that
2184 occupy eight times as much storage, and so on.
2186 The @code{INTEGER(KIND=2)} and @code{LOGICAL(KIND=2)} types
2187 are not necessarily supported by every GNU Fortran implementation.
2190 This corresponds to types that occupy as much
2191 storage as the default @code{CHARACTER} type,
2192 which is the same effective type as @code{CHARACTER(KIND=1)}
2193 (making that type effectively the same as @code{CHARACTER(KIND=3)}).
2195 (Typically, these are @code{INTEGER*1} and @code{LOGICAL*1}.)
2197 @var{n} of 6 thus corresponds to types that occupy twice as
2198 much storage as the @var{n}=3 types, @var{n} of 12 to types
2199 that occupy four times as much storage, and so on.
2201 These are not necessarily supported by every GNU Fortran
2205 This corresponds to types that occupy half the
2206 storage as the default (@var{n}=1) types.
2208 (Typically, these are @code{INTEGER*2} and @code{LOGICAL*2}.)
2210 @var{n} of 25 thus corresponds to types that occupy one-quarter
2211 as much storage as the default types.
2213 These are not necessarily supported by every GNU Fortran
2218 This is valid only as @code{INTEGER(KIND=7)} and
2219 denotes the @code{INTEGER} type that has the smallest
2220 storage size that holds a pointer on the system.
2222 A pointer representable by this type is capable of uniquely
2223 addressing a @code{CHARACTER*1} variable, array, array element,
2226 (Typically this is equivalent to @code{INTEGER*4} or,
2227 on 64-bit systems, @code{INTEGER*8}.
2228 In a compatible C implementation, it typically would
2229 be the same size and semantics of the C type @code{void *}.)
2232 Note that these are @emph{proposed} correspondences and might change
2233 in future versions of @command{g77}---avoid writing code depending
2234 on them while @command{g77}, and therefore the GNU Fortran language
2235 it defines, is in beta testing.
2237 Values not specified in the above list are reserved to
2238 future versions of the GNU Fortran language.
2240 Implementation-dependent meanings will be assigned new,
2241 unique prime numbers so as to not interfere with other
2242 implementation-dependent meanings, and offer the possibility
2243 of increasing the portability of code depending on such
2244 types by offering support for them in other GNU Fortran
2247 Other meanings that might be given unique values are:
2251 Types that make use of only half their storage size for
2252 representing precision and range.
2254 For example, some compilers offer options that cause
2255 @code{INTEGER} types to occupy the amount of storage
2256 that would be needed for @code{INTEGER(KIND=2)} types, but the
2257 range remains that of @code{INTEGER(KIND=1)}.
2260 The IEEE single floating-point type.
2263 Types with a specific bit pattern (endianness), such as the
2264 little-endian form of @code{INTEGER(KIND=1)}.
2265 These could permit, conceptually, use of portable code and
2266 implementations on data files written by existing systems.
2269 Future @emph{prime} numbers should be given meanings in as incremental
2270 a fashion as possible, to allow for flexibility and
2271 expressiveness in combining types.
2273 For example, instead of defining a prime number for little-endian
2274 IEEE doubles, one prime number might be assigned the meaning
2275 ``little-endian'', another the meaning ``IEEE double'', and the
2276 value of @var{n} for a little-endian IEEE double would thus
2277 naturally be the product of those two respective assigned values.
2278 (It could even be reasonable to have IEEE values result from the
2279 products of prime values denoting exponent and fraction sizes
2280 and meanings, hidden bit usage, availability and representations
2281 of special values such as subnormals, infinities, and Not-A-Numbers
2284 This assignment mechanism, while not inherently required for
2285 future versions of the GNU Fortran language, is worth using
2286 because it could ease management of the ``space'' of supported
2287 types much easier in the long run.
2289 The above approach suggests a mechanism for specifying inheritance
2290 of intrinsic (built-in) types for an entire, widely portable
2292 It is certainly reasonable that, unlike programmers of other languages
2293 offering inheritance mechanisms that employ verbose names for classes
2294 and subclasses, along with graphical browsers to elucidate the
2295 relationships, Fortran programmers would employ
2296 a mechanism that works by multiplying prime numbers together
2297 and finding the prime factors of such products.
2299 Most of the advantages for the above scheme have been explained
2301 One disadvantage is that it could lead to the defining,
2302 by the GNU Fortran language, of some fairly large prime numbers.
2303 This could lead to the GNU Fortran language being declared
2304 ``munitions'' by the United States Department of Defense.
2307 @subsection Constants
2309 @cindex types, constants
2311 (Corresponds to Section 4.2 of ANSI X3.9-1978 FORTRAN 77.)
2313 A @dfn{typeless constant} has one of the following forms:
2316 '@var{binary-digits}'B
2317 '@var{octal-digits}'O
2318 '@var{hexadecimal-digits}'Z
2319 '@var{hexadecimal-digits}'X
2323 @var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits}
2324 are nonempty strings of characters in the set @samp{01}, @samp{01234567},
2325 and @samp{0123456789ABCDEFabcdef}, respectively.
2326 (The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b}
2329 A prefix-radix constant, such as @samp{Z'ABCD'}, can optionally be
2330 treated as typeless. @xref{Fortran Dialect Options,, Options
2331 Controlling Fortran Dialect}, for information on the
2332 @option{-ftypeless-boz} option.
2334 Typeless constants have values that depend on the context in which
2337 All other constants, called @dfn{typed constants}, are interpreted---converted
2338 to internal form---according to their inherent type.
2339 Thus, context is @emph{never} a determining factor for the type, and hence
2340 the interpretation, of a typed constant.
2341 (All constants in the ANSI FORTRAN 77 language are typed constants.)
2343 For example, @samp{1} is always type @code{INTEGER(KIND=1)} in GNU
2344 Fortran (called default INTEGER in Fortran 90),
2345 @samp{9.435784839284958} is always type @code{REAL(KIND=1)} (even if the
2346 additional precision specified is lost, and even when used in a
2347 @code{REAL(KIND=2)} context), @samp{1E0} is always type @code{REAL(KIND=2)},
2348 and @samp{1D0} is always type @code{REAL(KIND=2)}.
2351 @subsection Integer Type
2353 (Corresponds to Section 4.3 of ANSI X3.9-1978 FORTRAN 77.)
2355 An integer constant also may have one of the following forms:
2358 B'@var{binary-digits}'
2359 O'@var{octal-digits}'
2360 Z'@var{hexadecimal-digits}'
2361 X'@var{hexadecimal-digits}'
2365 @var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits}
2366 are nonempty strings of characters in the set @samp{01}, @samp{01234567},
2367 and @samp{0123456789ABCDEFabcdef}, respectively.
2368 (The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b}
2371 @node Character Type
2372 @subsection Character Type
2374 (Corresponds to Section 4.8 of ANSI X3.9-1978 FORTRAN 77.)
2376 @cindex double quoted character constants
2377 A character constant may be delimited by a pair of double quotes
2378 (@samp{"}) instead of apostrophes.
2379 In this case, an apostrophe within the constant represents
2380 a single apostrophe, while a double quote is represented in
2381 the source text of the constant by two consecutive double
2382 quotes with no intervening spaces.
2384 @cindex zero-length CHARACTER
2385 @cindex null CHARACTER strings
2386 @cindex empty CHARACTER strings
2387 @cindex strings, empty
2388 @cindex CHARACTER, null
2389 A character constant may be empty (have a length of zero).
2391 A character constant may include a substring specification,
2392 The value of such a constant is the value of the substring---for
2393 example, the value of @samp{'hello'(3:5)} is the same
2394 as the value of @samp{'llo'}.
2397 @section Expressions
2399 (The following information augments or overrides the information in
2400 Chapter 6 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
2402 Chapter 6 of that document otherwise serves as the basis
2403 for the relevant aspects of GNU Fortran.)
2410 @subsection The @code{%LOC()} Construct
2411 @cindex %LOC() construct
2417 The @code{%LOC()} construct is an expression
2418 that yields the value of the location of its argument,
2419 @var{arg}, in memory.
2420 The size of the type of the expression depends on the system---typically,
2421 it is equivalent to either @code{INTEGER(KIND=1)} or @code{INTEGER(KIND=2)},
2422 though it is actually type @code{INTEGER(KIND=7)}.
2424 The argument to @code{%LOC()} must be suitable as the
2425 left-hand side of an assignment statement.
2426 That is, it may not be a general expression involving
2427 operators such as addition, subtraction, and so on,
2428 nor may it be a constant.
2430 Use of @code{%LOC()} is recommended only for code that
2431 is accessing facilities outside of GNU Fortran, such as
2432 operating system or windowing facilities.
2433 It is best to constrain such uses to isolated portions of
2434 a program---portions that deal specifically and exclusively
2435 with low-level, system-dependent facilities.
2436 Such portions might well provide a portable interface for
2437 use by the program as a whole, but are themselves not
2438 portable, and should be thoroughly tested each time they
2439 are rebuilt using a new compiler or version of a compiler.
2441 Do not depend on @code{%LOC()} returning a pointer that
2442 can be safely used to @emph{define} (change) the argument.
2443 While this might work in some circumstances, it is hard
2444 to predict whether it will continue to work when a program
2445 (that works using this unsafe behavior)
2446 is recompiled using different command-line options or
2447 a different version of @command{g77}.
2449 Generally, @code{%LOC()} is safe when used as an argument
2450 to a procedure that makes use of the value of the corresponding
2451 dummy argument only during its activation, and only when
2452 such use is restricted to referencing (reading) the value
2453 of the argument to @code{%LOC()}.
2455 @emph{Implementation Note:} Currently, @command{g77} passes
2456 arguments (those not passed using a construct such as @code{%VAL()})
2457 by reference or descriptor, depending on the type of
2458 the actual argument.
2459 Thus, given @samp{INTEGER I}, @samp{CALL FOO(I)} would
2460 seem to mean the same thing as @samp{CALL FOO(%VAL(%LOC(I)))}, and
2461 in fact might compile to identical code.
2463 However, @samp{CALL FOO(%VAL(%LOC(I)))} emphatically means
2464 ``pass, by value, the address of @samp{I} in memory''.
2465 While @samp{CALL FOO(I)} might use that same approach in a
2466 particular version of @command{g77}, another version or compiler
2467 might choose a different implementation, such as copy-in/copy-out,
2468 to effect the desired behavior---and which will therefore not
2469 necessarily compile to the same code as would
2470 @samp{CALL FOO(%VAL(%LOC(I)))}
2471 using the same version or compiler.
2473 @xref{Debugging and Interfacing}, for detailed information on
2474 how this particular version of @command{g77} implements various
2477 @node Specification Statements
2478 @section Specification Statements
2480 (The following information augments or overrides the information in
2481 Chapter 8 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
2483 Chapter 8 of that document otherwise serves as the basis
2484 for the relevant aspects of GNU Fortran.)
2492 @subsection @code{NAMELIST} Statement
2493 @cindex NAMELIST statement
2494 @cindex statements, NAMELIST
2496 The @code{NAMELIST} statement, and related I/O constructs, are
2497 supported by the GNU Fortran language in essentially the same
2498 way as they are by @command{f2c}.
2500 This follows Fortran 90 with the restriction that on @code{NAMELIST}
2501 input, subscripts must have the form
2503 @var{subscript} [ @code{:} @var{subscript} [ @code{:} @var{stride}]]
2507 &xx x(1:3,8:10:2)=1,2,3,4,5,6/
2509 is allowed, but not, say,
2511 &xx x(:3,8::2)=1,2,3,4,5,6/
2514 As an extension of the Fortran 90 form, @code{$} and @code{$END} may be
2515 used in place of @code{&} and @code{/} in @code{NAMELIST} input, so that
2517 $&xx x(1:3,8:10:2)=1,2,3,4,5,6 $end
2519 could be used instead of the example above.
2521 @node DOUBLE COMPLEX
2522 @subsection @code{DOUBLE COMPLEX} Statement
2523 @cindex DOUBLE COMPLEX
2525 @code{DOUBLE COMPLEX} is a type-statement (and type) that
2526 specifies the type @code{COMPLEX(KIND=2)} in GNU Fortran.
2528 @node Control Statements
2529 @section Control Statements
2531 (The following information augments or overrides the information in
2532 Chapter 11 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
2534 Chapter 11 of that document otherwise serves as the basis
2535 for the relevant aspects of GNU Fortran.)
2545 @subsection DO WHILE
2548 @cindex MIL-STD 1753
2550 The @code{DO WHILE} statement, a feature of both the MIL-STD 1753 and
2551 Fortran 90 standards, is provided by the GNU Fortran language.
2552 The Fortran 90 ``do forever'' statement comprising just @code{DO} is
2558 @cindex MIL-STD 1753
2560 The @code{END DO} statement is provided by the GNU Fortran language.
2562 This statement is used in one of two ways:
2566 The Fortran 90 meaning, in which it specifies the termination
2567 point of a single @code{DO} loop started with a @code{DO} statement
2568 that specifies no termination label.
2571 The MIL-STD 1753 meaning, in which it specifies the termination
2572 point of one or more @code{DO} loops, all of which start with a
2573 @code{DO} statement that specify the label defined for the
2574 @code{END DO} statement.
2576 This kind of @code{END DO} statement is merely a synonym for
2577 @code{CONTINUE}, except it is permitted only when the statement
2578 is labeled and a target of one or more labeled @code{DO} loops.
2580 It is expected that this use of @code{END DO} will be removed from
2581 the GNU Fortran language in the future, though it is likely that
2582 it will long be supported by @command{g77} as a dialect form.
2585 @node Construct Names
2586 @subsection Construct Names
2587 @cindex construct names
2589 The GNU Fortran language supports construct names as defined
2590 by the Fortran 90 standard.
2591 These names are local to the program unit and are defined
2595 @var{construct-name}: @var{block-statement}
2599 Here, @var{construct-name} is the construct name itself;
2600 its definition is connoted by the single colon (@samp{:}); and
2601 @var{block-statement} is an @code{IF}, @code{DO},
2602 or @code{SELECT CASE} statement that begins a block.
2604 A block that is given a construct name must also specify the
2605 same construct name in its termination statement:
2608 END @var{block} @var{construct-name}
2612 Here, @var{block} must be @code{IF}, @code{DO}, or @code{SELECT},
2615 @node CYCLE and EXIT
2616 @subsection The @code{CYCLE} and @code{EXIT} Statements
2618 @cindex CYCLE statement
2619 @cindex EXIT statement
2620 @cindex statements, CYCLE
2621 @cindex statements, EXIT
2622 The @code{CYCLE} and @code{EXIT} statements specify that
2623 the remaining statements in the current iteration of a
2624 particular active (enclosing) @code{DO} loop are to be skipped.
2626 @code{CYCLE} specifies that these statements are skipped,
2627 but the @code{END DO} statement that marks the end of the
2628 @code{DO} loop be executed---that is, the next iteration,
2629 if any, is to be started.
2630 If the statement marking the end of the @code{DO} loop is
2631 not @code{END DO}---in other words, if the loop is not
2632 a block @code{DO}---the @code{CYCLE} statement does not
2633 execute that statement, but does start the next iteration (if any).
2635 @code{EXIT} specifies that the loop specified by the
2636 @code{DO} construct is terminated.
2638 The @code{DO} loop affected by @code{CYCLE} and @code{EXIT}
2639 is the innermost enclosing @code{DO} loop when the following
2647 Otherwise, the following forms specify the construct name
2648 of the pertinent @code{DO} loop:
2651 CYCLE @var{construct-name}
2652 EXIT @var{construct-name}
2655 @code{CYCLE} and @code{EXIT} can be viewed as glorified @code{GO TO}
2657 However, they cannot be easily thought of as @code{GO TO} statements
2658 in obscure cases involving FORTRAN 77 loops.
2667 10 PRINT *, 'I=', I, ' J=', J, ' K=', K
2672 In particular, neither the @code{EXIT} nor @code{CYCLE} statements
2673 above are equivalent to a @code{GO TO} statement to either label
2674 @samp{10} or @samp{20}.
2676 To understand the effect of @code{CYCLE} and @code{EXIT} in the
2677 above fragment, it is helpful to first translate it to its equivalent
2678 using only block @code{DO} loops:
2686 10 PRINT *, 'I=', I, ' J=', J, ' K=', K
2693 Adding new labels allows translation of @code{CYCLE} and @code{EXIT}
2694 to @code{GO TO} so they may be more easily understood by programmers
2695 accustomed to FORTRAN coding:
2700 IF (J .EQ. 5) GOTO 18
2702 IF (K .EQ. 3) GO TO 12
2703 10 PRINT *, 'I=', I, ' J=', J, ' K=', K
2711 Thus, the @code{CYCLE} statement in the innermost loop skips over
2712 the @code{PRINT} statement as it begins the next iteration of the
2713 loop, while the @code{EXIT} statement in the middle loop ends that
2714 loop but @emph{not} the outermost loop.
2716 @node Functions and Subroutines
2717 @section Functions and Subroutines
2719 (The following information augments or overrides the information in
2720 Chapter 15 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
2722 Chapter 15 of that document otherwise serves as the basis
2723 for the relevant aspects of GNU Fortran.)
2729 * Generics and Specifics::
2730 * REAL() and AIMAG() of Complex::
2731 * CMPLX() of DOUBLE PRECISION::
2733 * f77/f2c Intrinsics::
2734 * Table of Intrinsic Functions::
2738 @subsection The @code{%VAL()} Construct
2739 @cindex %VAL() construct
2745 The @code{%VAL()} construct specifies that an argument,
2746 @var{arg}, is to be passed by value, instead of by reference
2749 @code{%VAL()} is restricted to actual arguments in
2750 invocations of external procedures.
2752 Use of @code{%VAL()} is recommended only for code that
2753 is accessing facilities outside of GNU Fortran, such as
2754 operating system or windowing facilities.
2755 It is best to constrain such uses to isolated portions of
2756 a program---portions the deal specifically and exclusively
2757 with low-level, system-dependent facilities.
2758 Such portions might well provide a portable interface for
2759 use by the program as a whole, but are themselves not
2760 portable, and should be thoroughly tested each time they
2761 are rebuilt using a new compiler or version of a compiler.
2763 @emph{Implementation Note:} Currently, @command{g77} passes
2764 all arguments either by reference or by descriptor.
2766 Thus, use of @code{%VAL()} tends to be restricted to cases
2767 where the called procedure is written in a language other
2768 than Fortran that supports call-by-value semantics.
2769 (C is an example of such a language.)
2771 @xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)},
2772 for detailed information on
2773 how this particular version of @command{g77} passes arguments
2777 @subsection The @code{%REF()} Construct
2778 @cindex %REF() construct
2784 The @code{%REF()} construct specifies that an argument,
2785 @var{arg}, is to be passed by reference, instead of by
2786 value or descriptor.
2788 @code{%REF()} is restricted to actual arguments in
2789 invocations of external procedures.
2791 Use of @code{%REF()} is recommended only for code that
2792 is accessing facilities outside of GNU Fortran, such as
2793 operating system or windowing facilities.
2794 It is best to constrain such uses to isolated portions of
2795 a program---portions the deal specifically and exclusively
2796 with low-level, system-dependent facilities.
2797 Such portions might well provide a portable interface for
2798 use by the program as a whole, but are themselves not
2799 portable, and should be thoroughly tested each time they
2800 are rebuilt using a new compiler or version of a compiler.
2802 Do not depend on @code{%REF()} supplying a pointer to the
2803 procedure being invoked.
2804 While that is a likely implementation choice, other
2805 implementation choices are available that preserve Fortran
2806 pass-by-reference semantics without passing a pointer to
2807 the argument, @var{arg}.
2808 (For example, a copy-in/copy-out implementation.)
2810 @emph{Implementation Note:} Currently, @command{g77} passes
2812 (other than variables and arrays of type @code{CHARACTER})
2814 Future versions of, or dialects supported by, @command{g77} might
2815 not pass @code{CHARACTER} functions by reference.
2817 Thus, use of @code{%REF()} tends to be restricted to cases
2818 where @var{arg} is type @code{CHARACTER} but the called
2819 procedure accesses it via a means other than the method
2820 used for Fortran @code{CHARACTER} arguments.
2822 @xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on
2823 how this particular version of @command{g77} passes arguments
2827 @subsection The @code{%DESCR()} Construct
2828 @cindex %DESCR() construct
2834 The @code{%DESCR()} construct specifies that an argument,
2835 @var{arg}, is to be passed by descriptor, instead of by
2838 @code{%DESCR()} is restricted to actual arguments in
2839 invocations of external procedures.
2841 Use of @code{%DESCR()} is recommended only for code that
2842 is accessing facilities outside of GNU Fortran, such as
2843 operating system or windowing facilities.
2844 It is best to constrain such uses to isolated portions of
2845 a program---portions the deal specifically and exclusively
2846 with low-level, system-dependent facilities.
2847 Such portions might well provide a portable interface for
2848 use by the program as a whole, but are themselves not
2849 portable, and should be thoroughly tested each time they
2850 are rebuilt using a new compiler or version of a compiler.
2852 Do not depend on @code{%DESCR()} supplying a pointer
2853 and/or a length passed by value
2854 to the procedure being invoked.
2855 While that is a likely implementation choice, other
2856 implementation choices are available that preserve the
2857 pass-by-reference semantics without passing a pointer to
2858 the argument, @var{arg}.
2859 (For example, a copy-in/copy-out implementation.)
2860 And, future versions of @command{g77} might change the
2861 way descriptors are implemented, such as passing a
2862 single argument pointing to a record containing the
2863 pointer/length information instead of passing that same
2864 information via two arguments as it currently does.
2866 @emph{Implementation Note:} Currently, @command{g77} passes
2867 all variables and arrays of type @code{CHARACTER}
2869 Future versions of, or dialects supported by, @command{g77} might
2870 pass @code{CHARACTER} functions by descriptor as well.
2872 Thus, use of @code{%DESCR()} tends to be restricted to cases
2873 where @var{arg} is not type @code{CHARACTER} but the called
2874 procedure accesses it via a means similar to the method
2875 used for Fortran @code{CHARACTER} arguments.
2877 @xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on
2878 how this particular version of @command{g77} passes arguments
2881 @node Generics and Specifics
2882 @subsection Generics and Specifics
2883 @cindex generic intrinsics
2884 @cindex intrinsics, generic
2886 The ANSI FORTRAN 77 language defines generic and specific
2888 In short, the distinctions are:
2892 @emph{Specific} intrinsics have
2893 specific types for their arguments and a specific return
2897 @emph{Generic} intrinsics are treated,
2898 on a case-by-case basis in the program's source code,
2899 as one of several possible specific intrinsics.
2901 Typically, a generic intrinsic has a return type that
2902 is determined by the type of one or more of its arguments.
2905 The GNU Fortran language generalizes these concepts somewhat,
2906 especially by providing intrinsic subroutines and generic
2907 intrinsics that are treated as either a specific intrinsic subroutine
2908 or a specific intrinsic function (e.g. @code{SECOND}).
2910 However, GNU Fortran avoids generalizing this concept to
2911 the point where existing code would be accepted as meaning
2912 something possibly different than what was intended.
2914 For example, @code{ABS} is a generic intrinsic, so all working
2915 code written using @code{ABS} of an @code{INTEGER} argument
2916 expects an @code{INTEGER} return value.
2917 Similarly, all such code expects that @code{ABS} of an @code{INTEGER*2}
2918 argument returns an @code{INTEGER*2} return value.
2920 Yet, @code{IABS} is a @emph{specific} intrinsic that accepts only
2921 an @code{INTEGER(KIND=1)} argument.
2922 Code that passes something other than an @code{INTEGER(KIND=1)}
2923 argument to @code{IABS} is not valid GNU Fortran code, because
2924 it is not clear what the author intended.
2926 For example, if @samp{J} is @code{INTEGER(KIND=6)}, @samp{IABS(J)}
2927 is not defined by the GNU Fortran language, because the programmer
2928 might have used that construct to mean any of the following, subtly
2933 Convert @samp{J} to @code{INTEGER(KIND=1)} first
2934 (as if @samp{IABS(INT(J))} had been written).
2937 Convert the result of the intrinsic to @code{INTEGER(KIND=1)}
2938 (as if @samp{INT(ABS(J))} had been written).
2941 No conversion (as if @samp{ABS(J)} had been written).
2944 The distinctions matter especially when types and values wider than
2945 @code{INTEGER(KIND=1)} (such as @code{INTEGER(KIND=2)}), or when
2946 operations performing more ``arithmetic'' than absolute-value, are involved.
2948 The following sample program is not a valid GNU Fortran program, but
2949 might be accepted by other compilers.
2950 If so, the output is likely to be revealing in terms of how a given
2951 compiler treats intrinsics (that normally are specific) when they
2952 are given arguments that do not conform to their stated requirements:
2954 @cindex JCB002 program
2958 C Modified 1999-02-15 (Burley) to delete my email address.
2959 C Modified 1997-05-21 (Burley) to accommodate compilers that implement
2960 C INT(I1-I2) as INT(I1)-INT(I2) given INTEGER*2 I1,I2.
2963 C Written by James Craig Burley 1997-02-20.
2966 C Determine how compilers handle non-standard IDIM
2967 C on INTEGER*2 operands, which presumably can be
2968 C extrapolated into understanding how the compiler
2969 C generally treats specific intrinsics that are passed
2970 C arguments not of the correct types.
2972 C If your compiler implements INTEGER*2 and INTEGER
2973 C as the same type, change all INTEGER*2 below to
2978 INTEGER*2 ISMALL, ILARGE
2979 INTEGER*2 ITOOLG, ITWO
2983 C Find smallest INTEGER*2 number.
2987 IF ((I0 .GE. ISMALL) .OR. (I0+1 .NE. ISMALL)) GOTO 20
2992 C Find largest INTEGER*2 number.
2996 IF ((I0 .LE. ILARGE) .OR. (I0-1 .NE. ILARGE)) GOTO 40
3001 C Multiplying by two adds stress to the situation.
3005 C Need a number that, added to -2, is too wide to fit in I*2.
3009 C Use IDIM the straightforward way.
3011 I1 = IDIM (ILARGE, ISMALL) * ITWO + ITOOLG
3013 C Calculate result for first interpretation.
3015 I2 = (INT (ILARGE) - INT (ISMALL)) * ITWO + ITOOLG
3017 C Calculate result for second interpretation.
3019 ITMP = ILARGE - ISMALL
3020 I3 = (INT (ITMP)) * ITWO + ITOOLG
3022 C Calculate result for third interpretation.
3024 I4 = (ILARGE - ISMALL) * ITWO + ITOOLG
3028 PRINT *, 'ILARGE=', ILARGE
3029 PRINT *, 'ITWO=', ITWO
3030 PRINT *, 'ITOOLG=', ITOOLG
3031 PRINT *, 'ISMALL=', ISMALL
3040 IF (L2 .AND. .NOT.L3 .AND. .NOT.L4) THEN
3041 PRINT *, 'Interp 1: IDIM(I*2,I*2) => IDIM(INT(I*2),INT(I*2))'
3044 IF (L3 .AND. .NOT.L2 .AND. .NOT.L4) THEN
3045 PRINT *, 'Interp 2: IDIM(I*2,I*2) => INT(DIM(I*2,I*2))'
3048 IF (L4 .AND. .NOT.L2 .AND. .NOT.L3) THEN
3049 PRINT *, 'Interp 3: IDIM(I*2,I*2) => DIM(I*2,I*2)'
3052 PRINT *, 'Results need careful analysis.'
3056 No future version of the GNU Fortran language
3057 will likely permit specific intrinsic invocations with wrong-typed
3058 arguments (such as @code{IDIM} in the above example), since
3059 it has been determined that disagreements exist among
3060 many production compilers on the interpretation of
3062 These disagreements strongly suggest that Fortran programmers,
3063 and certainly existing Fortran programs, disagree about the
3064 meaning of such invocations.
3066 The first version of @code{JCB002} didn't accommodate some compilers'
3067 treatment of @samp{INT(I1-I2)} where @samp{I1} and @samp{I2} are
3069 In such a case, these compilers apparently convert both
3070 operands to @code{INTEGER*4} and then do an @code{INTEGER*4} subtraction,
3071 instead of doing an @code{INTEGER*2} subtraction on the
3072 original values in @samp{I1} and @samp{I2}.
3074 However, the results of the careful analyses done on the outputs
3075 of programs compiled by these various compilers show that they
3076 all implement either @samp{Interp 1} or @samp{Interp 2} above.
3078 Specifically, it is believed that the new version of @code{JCB002}
3079 above will confirm that:
3083 Digital Semiconductor (``DEC'') Alpha OSF/1, HP-UX 10.0.1, AIX 3.2.5
3084 @command{f77} compilers all implement @samp{Interp 1}.
3087 IRIX 5.3 @command{f77} compiler implements @samp{Interp 2}.
3090 Solaris 2.5, SunOS 4.1.3, DECstation ULTRIX 4.3,
3091 and IRIX 6.1 @command{f77} compilers all implement @samp{Interp 3}.
3094 If you get different results than the above for the stated
3095 compilers, or have results for other compilers that might be
3096 worth adding to the above list, please let us know the details
3097 (compiler product, version, machine, results, and so on).
3099 @node REAL() and AIMAG() of Complex
3100 @subsection @code{REAL()} and @code{AIMAG()} of Complex
3101 @cindex @code{Real} intrinsic
3102 @cindex intrinsics, @code{Real}
3103 @cindex @code{AImag} intrinsic
3104 @cindex intrinsics, @code{AImag}
3106 The GNU Fortran language disallows @code{REAL(@var{expr})}
3107 and @code{AIMAG(@var{expr})},
3108 where @var{expr} is any @code{COMPLEX} type other than @code{COMPLEX(KIND=1)},
3109 except when they are used in the following way:
3112 REAL(REAL(@var{expr}))
3113 REAL(AIMAG(@var{expr}))
3117 The above forms explicitly specify that the desired effect
3118 is to convert the real or imaginary part of @var{expr}, which might
3119 be some @code{REAL} type other than @code{REAL(KIND=1)},
3120 to type @code{REAL(KIND=1)},
3121 and have that serve as the value of the expression.
3123 The GNU Fortran language offers clearly named intrinsics to extract the
3124 real and imaginary parts of a complex entity without any
3128 REALPART(@var{expr})
3129 IMAGPART(@var{expr})
3132 To express the above using typical extended FORTRAN 77,
3133 use the following constructs
3134 (when @var{expr} is @code{COMPLEX(KIND=2)}):
3141 The FORTRAN 77 language offers no way
3142 to explicitly specify the real and imaginary parts of a complex expression of
3143 arbitrary type, apparently as a result of requiring support for
3144 only one @code{COMPLEX} type (@code{COMPLEX(KIND=1)}).
3145 The concepts of converting an expression to type @code{REAL(KIND=1)} and
3146 of extracting the real part of a complex expression were
3147 thus ``smooshed'' by FORTRAN 77 into a single intrinsic, since
3148 they happened to have the exact same effect in that language
3149 (due to having only one @code{COMPLEX} type).
3151 @emph{Note:} When @option{-ff90} is in effect,
3152 @command{g77} treats @samp{REAL(@var{expr})}, where @var{expr} is of
3153 type @code{COMPLEX}, as @samp{REALPART(@var{expr})},
3154 whereas with @samp{-fugly-complex -fno-f90} in effect, it is
3155 treated as @samp{REAL(REALPART(@var{expr}))}.
3157 @xref{Ugly Complex Part Extraction}, for more information.
3159 @node CMPLX() of DOUBLE PRECISION
3160 @subsection @code{CMPLX()} of @code{DOUBLE PRECISION}
3161 @cindex @code{Cmplx} intrinsic
3162 @cindex intrinsics, @code{Cmplx}
3164 In accordance with Fortran 90 and at least some (perhaps all)
3165 other compilers, the GNU Fortran language defines @code{CMPLX()}
3166 as always returning a result that is type @code{COMPLEX(KIND=1)}.
3168 This means @samp{CMPLX(D1,D2)}, where @samp{D1} and @samp{D2}
3169 are @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}), is treated as:
3172 CMPLX(SNGL(D1), SNGL(D2))
3175 (It was necessary for Fortran 90 to specify this behavior
3176 for @code{DOUBLE PRECISION} arguments, since that is
3177 the behavior mandated by FORTRAN 77.)
3179 The GNU Fortran language also provides the @code{DCMPLX()} intrinsic,
3180 which is provided by some FORTRAN 77 compilers to construct
3181 a @code{DOUBLE COMPLEX} entity from of @code{DOUBLE PRECISION}
3183 However, this solution does not scale well when more @code{COMPLEX} types
3184 (having various precisions and ranges) are offered by Fortran implementations.
3186 Fortran 90 extends the @code{CMPLX()} intrinsic by adding
3187 an extra argument used to specify the desired kind of complex
3189 However, this solution is somewhat awkward to use, and
3190 @command{g77} currently does not support it.
3192 The GNU Fortran language provides a simple way to build a complex
3193 value out of two numbers, with the precise type of the value
3194 determined by the types of the two numbers (via the usual
3195 type-promotion mechanism):
3198 COMPLEX(@var{real}, @var{imag})
3201 When @var{real} and @var{imag} are the same @code{REAL} types, @code{COMPLEX()}
3202 performs no conversion other than to put them together to form a
3203 complex result of the same (complex version of real) type.
3205 @xref{Complex Intrinsic}, for more information.
3208 @subsection MIL-STD 1753 Support
3209 @cindex MIL-STD 1753
3211 The GNU Fortran language includes the MIL-STD 1753 intrinsics
3212 @code{BTEST}, @code{IAND}, @code{IBCLR}, @code{IBITS},
3213 @code{IBSET}, @code{IEOR}, @code{IOR}, @code{ISHFT},
3214 @code{ISHFTC}, @code{MVBITS}, and @code{NOT}.
3216 @node f77/f2c Intrinsics
3217 @subsection @command{f77}/@command{f2c} Intrinsics
3219 The bit-manipulation intrinsics supported by traditional
3220 @command{f77} and by @command{f2c} are available in the GNU Fortran language.
3221 These include @code{AND}, @code{LSHIFT}, @code{OR}, @code{RSHIFT},
3224 Also supported are the intrinsics @code{CDABS},
3225 @code{CDCOS}, @code{CDEXP}, @code{CDLOG}, @code{CDSIN},
3226 @code{CDSQRT}, @code{DCMPLX}, @code{DCONJG}, @code{DFLOAT},
3227 @code{DIMAG}, @code{DREAL}, and @code{IMAG},
3228 @code{ZABS}, @code{ZCOS}, @code{ZEXP}, @code{ZLOG}, @code{ZSIN},
3231 @node Table of Intrinsic Functions
3232 @subsection Table of Intrinsic Functions
3233 @cindex intrinsics, table of
3234 @cindex table of intrinsics
3236 (Corresponds to Section 15.10 of ANSI X3.9-1978 FORTRAN 77.)
3238 The GNU Fortran language adds various functions, subroutines, types,
3239 and arguments to the set of intrinsic functions in ANSI FORTRAN 77.
3240 The complete set of intrinsics supported by the GNU Fortran language
3243 Note that a name is not treated as that of an intrinsic if it is
3244 specified in an @code{EXTERNAL} statement in the same program unit;
3245 if a command-line option is used to disable the groups to which
3246 the intrinsic belongs; or if the intrinsic is not named in an
3247 @code{INTRINSIC} statement and a command-line option is used to
3248 hide the groups to which the intrinsic belongs.
3250 So, it is recommended that any reference in a program unit to
3251 an intrinsic procedure that is not a standard FORTRAN 77
3252 intrinsic be accompanied by an appropriate @code{INTRINSIC}
3253 statement in that program unit.
3254 This sort of defensive programming makes it more
3255 likely that an implementation will issue a diagnostic rather
3256 than generate incorrect code for such a reference.
3258 The terminology used below is based on that of the Fortran 90
3259 standard, so that the text may be more concise and accurate:
3263 @code{OPTIONAL} means the argument may be omitted.
3266 @samp{A-1, A-2, @dots{}, A-n} means more than one argument
3267 (generally named @samp{A}) may be specified.
3270 @samp{scalar} means the argument must not be an array (must
3271 be a variable or array element, or perhaps a constant if expressions
3275 @samp{DIMENSION(4)} means the argument must be an array having 4 elements.
3278 @code{INTENT(IN)} means the argument must be an expression
3279 (such as a constant or a variable that is defined upon invocation
3283 @code{INTENT(OUT)} means the argument must be definable by the
3284 invocation of the intrinsic (that is, must not be a constant nor
3285 an expression involving operators other than array reference and
3286 substring reference).
3289 @code{INTENT(INOUT)} means the argument must be defined prior to,
3290 and definable by, invocation of the intrinsic (a combination of
3291 the requirements of @code{INTENT(IN)} and @code{INTENT(OUT)}.
3294 @xref{Kind Notation}, for an explanation of @code{KIND}.
3298 (Note that the empty lines appearing in the menu below
3299 are not intentional---they result from a bug in the
3300 GNU @command{makeinfo} program@dots{}a program that, if it
3301 did not exist, would leave this document in far worse shape!)
3304 @c The actual documentation for intrinsics comes from
3305 @c intdoc.texi, which in turn is automatically generated
3306 @c from the internal g77 tables in intrin.def _and_ the
3307 @c largely hand-written text in intdoc.h. So, if you want
3308 @c to change or add to existing documentation on intrinsics,
3309 @c you probably want to edit intdoc.h.
3321 @include intdoc.texi
3323 @node Scope and Classes of Names
3324 @section Scope and Classes of Symbolic Names
3325 @cindex symbol names, scope and classes
3328 (The following information augments or overrides the information in
3329 Chapter 18 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
3331 Chapter 18 of that document otherwise serves as the basis
3332 for the relevant aspects of GNU Fortran.)
3335 * Underscores in Symbol Names::
3338 @node Underscores in Symbol Names
3339 @subsection Underscores in Symbol Names
3342 Underscores (@samp{_}) are accepted in symbol names after the first
3343 character (which must be a letter).
3349 A dollar sign at the end of an output format specification suppresses
3350 the newline at the end of the output.
3352 @cindex <> edit descriptor
3353 @cindex edit descriptor, <>
3354 Edit descriptors in @code{FORMAT} statements may contain compile-time
3355 @code{INTEGER} constant expressions in angle brackets, such as
3357 10 FORMAT (I<WIDTH>)
3360 The @code{OPEN} specifier @code{NAME=} is equivalent to @code{FILE=}.
3362 These Fortran 90 features are supported:
3365 @cindex FORMAT descriptors
3366 @cindex Z edit descriptor
3367 @cindex edit descriptor, Z
3368 @cindex O edit descriptor
3369 @cindex edit descriptor, O
3370 The @code{O} and @code{Z} edit descriptors are supported for I/O of
3371 integers in octal and hexadecimal formats, respectively.
3373 The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if
3374 @code{STATUS='SCRATCH'} is supplied. The @code{STATUS='REPLACE'}
3375 specifier is supported.
3378 @node Fortran 90 Features
3379 @section Fortran 90 Features
3381 @cindex extensions, from Fortran 90
3383 For convenience this section collects a list (probably incomplete) of
3384 the Fortran 90 features supported by the GNU Fortran language, even if
3385 they are documented elsewhere.
3386 @xref{Characters Lines Sequence,,@asis{Characters, Lines, and Execution Sequence}},
3387 for information on additional fixed source form lexical issues.
3388 @cindex @option{-ffree-form}
3389 Further, the free source form is supported through the
3390 @option{-ffree-form} option.
3391 @cindex @option{-ff90}
3392 Other Fortran 90 features can be turned on by the @option{-ff90} option;
3393 see @ref{Fortran 90}.
3394 For information on the Fortran 90 intrinsics available,
3395 see @ref{Table of Intrinsic Functions}.
3398 @item Automatic arrays in procedures
3399 @item Character assignments
3400 @cindex character assignments
3401 In character assignments, the variable being assigned may occur on the
3402 right hand side of the assignment.
3403 @item Character strings
3404 @cindex double quoted character constants
3405 Strings may have zero length and substrings of character constants are
3406 permitted. Character constants may be enclosed in double quotes
3407 (@code{"}) as well as single quotes. @xref{Character Type}.
3408 @item Construct names
3409 (Symbolic tags on blocks.) @xref{Construct Names}.
3410 @item @code{CYCLE} and @code{EXIT}
3411 @xref{CYCLE and EXIT,,The @code{CYCLE} and @code{EXIT} Statements}.
3412 @item @code{DOUBLE COMPLEX}
3413 @xref{DOUBLE COMPLEX,,@code{DOUBLE COMPLEX} Statement}.
3414 @item @code{DO WHILE}
3416 @item @code{END} decoration
3421 @item @code{IMPLICIT NONE}
3422 @item @code{INCLUDE} statements
3424 @item List-directed and namelist I/O on internal files
3425 @item Binary, octal and hexadecimal constants
3426 These are supported more generally than required by Fortran 90.
3427 @xref{Integer Type}.
3428 @item @samp{O} and @samp{Z} edit descriptors
3429 @item @code{NAMELIST}
3431 @item @code{OPEN} specifiers
3432 @code{STATUS='REPLACE'} is supported.
3433 The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if
3434 @code{STATUS='SCRATCH'} is supplied.
3435 @item @code{FORMAT} edit descriptors
3436 @cindex FORMAT descriptors
3437 @cindex Z edit descriptor
3438 @cindex edit descriptor, Z
3439 The @code{Z} edit descriptor is supported.
3440 @item Relational operators
3441 The operators @code{<}, @code{<=}, @code{==}, @code{/=}, @code{>} and
3442 @code{>=} may be used instead of @code{.LT.}, @code{.LE.}, @code{.EQ.},
3443 @code{.NE.}, @code{.GT.} and @code{.GE.} respectively.
3444 @item @code{SELECT CASE}
3445 Not fully implemented.
3446 @xref{SELECT CASE on CHARACTER Type,, @code{SELECT CASE} on @code{CHARACTER} Type}.
3447 @item Specification statements
3448 A limited subset of the Fortran 90 syntax and semantics for variable
3449 declarations is supported, including @code{KIND}. @xref{Kind Notation}.
3450 (@code{KIND} is of limited usefulness in the absence of the
3451 @code{KIND}-related intrinsics, since these intrinsics permit writing
3452 more widely portable code.) An example of supported @code{KIND} usage
3455 INTEGER (KIND=1) :: FOO=1, BAR=2
3456 CHARACTER (LEN=3) FOO
3458 @code{PARAMETER} and @code{DIMENSION} attributes aren't supported.
3461 @node Other Dialects
3462 @chapter Other Dialects
3464 GNU Fortran supports a variety of features that are not
3465 considered part of the GNU Fortran language itself, but
3466 are representative of various dialects of Fortran that
3467 @command{g77} supports in whole or in part.
3469 Any of the features listed below might be disallowed by
3470 @command{g77} unless some command-line option is specified.
3471 Currently, some of the features are accepted using the
3472 default invocation of @command{g77}, but that might change
3475 @emph{Note: This portion of the documentation definitely needs a lot
3479 * Source Form:: Details of fixed-form and free-form source.
3480 * Trailing Comment:: Use of @samp{/*} to start a comment.
3481 * Debug Line:: Use of @samp{D} in column 1.
3482 * Dollar Signs:: Use of @samp{$} in symbolic names.
3483 * Case Sensitivity:: Uppercase and lowercase in source files.
3484 * VXT Fortran:: @dots{}versus the GNU Fortran language.
3485 * Fortran 90:: @dots{}versus the GNU Fortran language.
3486 * Pedantic Compilation:: Enforcing the standard.
3487 * Distensions:: Misfeatures supported by GNU Fortran.
3491 @section Source Form
3492 @cindex source file format
3493 @cindex source format
3494 @cindex file, source
3496 @cindex code, source
3500 GNU Fortran accepts programs written in either fixed form or
3504 corresponds to ANSI FORTRAN 77 (plus popular extensions, such as
3505 allowing tabs) and Fortran 90's fixed form.
3507 Free form corresponds to
3508 Fortran 90's free form (though possibly not entirely up-to-date, and
3509 without complaining about some things that for which Fortran 90 requires
3510 diagnostics, such as the spaces in the constant in @samp{R = 3 . 1}).
3512 The way a Fortran compiler views source files depends entirely on the
3513 implementation choices made for the compiler, since those choices
3514 are explicitly left to the implementation by the published Fortran
3516 GNU Fortran currently tries to be somewhat like a few popular compilers
3517 (@command{f2c}, Digital (``DEC'') Fortran, and so on).
3519 This section describes how @command{g77} interprets source lines.
3522 * Carriage Returns:: Carriage returns ignored.
3523 * Tabs:: Tabs converted to spaces.
3524 * Short Lines:: Short lines padded with spaces (fixed-form only).
3525 * Long Lines:: Long lines truncated.
3526 * Ampersands:: Special Continuation Lines.
3529 @node Carriage Returns
3530 @subsection Carriage Returns
3531 @cindex carriage returns
3533 Carriage returns (@samp{\r}) in source lines are ignored.
3534 This is somewhat different from @command{f2c}, which seems to treat them as
3535 spaces outside character/Hollerith constants, and encodes them as @samp{\r}
3536 inside such constants.
3540 @cindex tab character
3541 @cindex horizontal tab
3543 A source line with a @key{TAB} character anywhere in it is treated as
3544 entirely significant---however long it is---instead of ending in
3545 column 72 (for fixed-form source) or 132 (for free-form source).
3546 This also is different from @command{f2c}, which encodes tabs as
3547 @samp{\t} (the ASCII @key{TAB} character) inside character
3548 and Hollerith constants, but nevertheless seems to treat the column
3549 position as if it had been affected by the canonical tab positioning.
3551 @command{g77} effectively
3552 translates tabs to the appropriate number of spaces (a la the default
3553 for the UNIX @command{expand} command) before doing any other processing, other
3554 than (currently) noting whether a tab was found on a line and using this
3555 information to decide how to interpret the length of the line and continued
3559 @subsection Short Lines
3560 @cindex short source lines
3561 @cindex space, padding with
3562 @cindex source lines, short
3563 @cindex lines, short
3565 Source lines shorter than the applicable fixed-form length are treated as
3566 if they were padded with spaces to that length.
3567 (None of this is relevant to source files written in free form.)
3570 continued character and Hollerith constants, and is a different
3571 interpretation than provided by some other popular compilers
3572 (although a bit more consistent with the traditional punched-card
3573 basis of Fortran and the way the Fortran standard expressed fixed
3576 @command{g77} might someday offer an option to warn about cases where differences
3577 might be seen as a result of this treatment, and perhaps an option to
3578 specify the alternate behavior as well.
3580 Note that this padding cannot apply to lines that are effectively of
3581 infinite length---such lines are specified using command-line options
3582 like @option{-ffixed-line-length-none}, for example.
3585 @subsection Long Lines
3586 @cindex long source lines
3587 @cindex truncation, of long lines
3589 @cindex source lines, long
3591 Source lines longer than the applicable length are truncated to that
3593 Currently, @command{g77} does not warn if the truncated characters are
3594 not spaces, to accommodate existing code written for systems that
3595 treated truncated text as commentary (especially in columns 73 through 80).
3597 @xref{Fortran Dialect Options,,Options Controlling Fortran Dialect},
3598 for information on the @option{-ffixed-line-length-@var{n}} option,
3599 which can be used to set the line length applicable to fixed-form
3603 @subsection Ampersand Continuation Line
3604 @cindex ampersand continuation line
3605 @cindex continuation line, ampersand
3607 A @samp{&} in column 1 of fixed-form source denotes an arbitrary-length
3608 continuation line, imitating the behavior of @command{f2c}.
3610 @node Trailing Comment
3611 @section Trailing Comment
3613 @cindex trailing comment
3615 @cindex characters, comment
3618 @cindex exclamation point
3619 @command{g77} supports use of @samp{/*} to start a trailing
3621 In the GNU Fortran language, @samp{!} is used for this purpose.
3623 @samp{/*} is not in the GNU Fortran language
3624 because the use of @samp{/*} in a program might
3625 suggest to some readers that a block, not trailing, comment is
3626 started (and thus ended by @samp{*/}, not end of line),
3627 since that is the meaning of @samp{/*} in C.
3629 Also, such readers might think they can use @samp{//} to start
3630 a trailing comment as an alternative to @samp{/*}, but
3631 @samp{//} already denotes concatenation, and such a ``comment''
3632 might actually result in a program that compiles without
3633 error (though it would likely behave incorrectly).
3638 @cindex comment line, debug
3640 Use of @samp{D} or @samp{d} as the first character (column 1) of
3641 a source line denotes a debug line.
3643 In turn, a debug line is treated as either a comment line
3644 or a normal line, depending on whether debug lines are enabled.
3646 When treated as a comment line, a line beginning with @samp{D} or
3647 @samp{d} is treated as if it the first character was @samp{C} or @samp{c}, respectively.
3648 When treated as a normal line, such a line is treated as if
3649 the first character was @key{SPC} (space).
3651 (Currently, @command{g77} provides no means for treating debug
3652 lines as normal lines.)
3655 @section Dollar Signs in Symbol Names
3659 Dollar signs (@samp{$}) are allowed in symbol names (after the first character)
3660 when the @option{-fdollar-ok} option is specified.
3662 @node Case Sensitivity
3663 @section Case Sensitivity
3664 @cindex case sensitivity
3665 @cindex source file format
3666 @cindex code, source
3668 @cindex uppercase letters
3669 @cindex lowercase letters
3670 @cindex letters, uppercase
3671 @cindex letters, lowercase
3673 GNU Fortran offers the programmer way too much flexibility in deciding
3674 how source files are to be treated vis-a-vis uppercase and lowercase
3676 There are 66 useful settings that affect case sensitivity, plus 10
3677 settings that are nearly useless, with the remaining 116 settings
3678 being either redundant or useless.
3680 None of these settings have any effect on the contents of comments
3681 (the text after a @samp{c} or @samp{C} in Column 1, for example)
3682 or of character or Hollerith constants.
3683 Note that things like the @samp{E} in the statement
3684 @samp{CALL FOO(3.2E10)} and the @samp{TO} in @samp{ASSIGN 10 TO LAB}
3685 are considered built-in keywords, and so are affected by
3688 Low-level switches are identified in this section as follows:
3692 Source Case Conversion:
3696 Preserve (see Note 1)
3698 Convert to Upper Case
3700 Convert to Lower Case
3704 Built-in Keyword Matching:
3708 Match Any Case (per-character basis)
3710 Match Upper Case Only
3712 Match Lower Case Only
3714 Match InitialCaps Only (see tables for spellings)
3718 Built-in Intrinsic Matching:
3722 Match Any Case (per-character basis)
3724 Match Upper Case Only
3726 Match Lower Case Only
3728 Match InitialCaps Only (see tables for spellings)
3732 User-defined Symbol Possibilities (warnings only):
3736 Allow Any Case (per-character basis)
3738 Allow Upper Case Only
3740 Allow Lower Case Only
3742 Allow InitialCaps Only (see Note 2)
3746 Note 1: @command{g77} eventually will support @code{NAMELIST} in a manner that is
3747 consistent with these source switches---in the sense that input will be
3748 expected to meet the same requirements as source code in terms
3749 of matching symbol names and keywords (for the exponent letters).
3751 Currently, however, @code{NAMELIST} is supported by @code{libg2c},
3752 which uppercases @code{NAMELIST} input and symbol names for matching.
3753 This means not only that @code{NAMELIST} output currently shows symbol
3754 (and keyword) names in uppercase even if lower-case source
3755 conversion (option A2) is selected, but that @code{NAMELIST} cannot be
3756 adequately supported when source case preservation (option A0)
3759 If A0 is selected, a warning message will be
3760 output for each @code{NAMELIST} statement to this effect.
3762 of the program is undefined at run time if two or more symbol names
3763 appear in a given @code{NAMELIST} such that the names are identical
3764 when converted to upper case (e.g. @samp{NAMELIST /X/ VAR, Var, var}).
3765 For complete and total elegance, perhaps there should be a warning
3766 when option A2 is selected, since the output of NAMELIST is currently
3767 in uppercase but will someday be lowercase (when a @code{libg77} is written),
3768 but that seems to be overkill for a product in beta test.
3770 Note 2: Rules for InitialCaps names are:
3774 Must be a single uppercase letter, @strong{or}
3776 Must start with an uppercase letter and contain at least one
3780 So @samp{A}, @samp{Ab}, @samp{ABc}, @samp{AbC}, and @samp{Abc} are
3781 valid InitialCaps names, but @samp{AB}, @samp{A2}, and @samp{ABC} are
3783 Note that most, but not all, built-in names meet these
3784 requirements---the exceptions are some of the two-letter format
3785 specifiers, such as @code{BN} and @code{BZ}.
3787 Here are the names of the corresponding command-line options:
3790 A0: -fsource-case-preserve
3791 A1: -fsource-case-upper
3792 A2: -fsource-case-lower
3794 B0: -fmatch-case-any
3795 B1: -fmatch-case-upper
3796 B2: -fmatch-case-lower
3797 B3: -fmatch-case-initcap
3799 C0: -fintrin-case-any
3800 C1: -fintrin-case-upper
3801 C2: -fintrin-case-lower
3802 C3: -fintrin-case-initcap
3804 D0: -fsymbol-case-any
3805 D1: -fsymbol-case-upper
3806 D2: -fsymbol-case-lower
3807 D3: -fsymbol-case-initcap
3810 Useful combinations of the above settings, along with abbreviated
3811 option names that set some of these combinations all at once:
3814 1: A0-- B0--- C0--- D0--- -fcase-preserve
3815 2: A0-- B0--- C0--- D-1--
3816 3: A0-- B0--- C0--- D--2-
3817 4: A0-- B0--- C0--- D---3
3818 5: A0-- B0--- C-1-- D0---
3819 6: A0-- B0--- C-1-- D-1--
3820 7: A0-- B0--- C-1-- D--2-
3821 8: A0-- B0--- C-1-- D---3
3822 9: A0-- B0--- C--2- D0---
3823 10: A0-- B0--- C--2- D-1--
3824 11: A0-- B0--- C--2- D--2-
3825 12: A0-- B0--- C--2- D---3
3826 13: A0-- B0--- C---3 D0---
3827 14: A0-- B0--- C---3 D-1--
3828 15: A0-- B0--- C---3 D--2-
3829 16: A0-- B0--- C---3 D---3
3830 17: A0-- B-1-- C0--- D0---
3831 18: A0-- B-1-- C0--- D-1--
3832 19: A0-- B-1-- C0--- D--2-
3833 20: A0-- B-1-- C0--- D---3
3834 21: A0-- B-1-- C-1-- D0---
3835 22: A0-- B-1-- C-1-- D-1-- -fcase-strict-upper
3836 23: A0-- B-1-- C-1-- D--2-
3837 24: A0-- B-1-- C-1-- D---3
3838 25: A0-- B-1-- C--2- D0---
3839 26: A0-- B-1-- C--2- D-1--
3840 27: A0-- B-1-- C--2- D--2-
3841 28: A0-- B-1-- C--2- D---3
3842 29: A0-- B-1-- C---3 D0---
3843 30: A0-- B-1-- C---3 D-1--
3844 31: A0-- B-1-- C---3 D--2-
3845 32: A0-- B-1-- C---3 D---3
3846 33: A0-- B--2- C0--- D0---
3847 34: A0-- B--2- C0--- D-1--
3848 35: A0-- B--2- C0--- D--2-
3849 36: A0-- B--2- C0--- D---3
3850 37: A0-- B--2- C-1-- D0---
3851 38: A0-- B--2- C-1-- D-1--
3852 39: A0-- B--2- C-1-- D--2-
3853 40: A0-- B--2- C-1-- D---3
3854 41: A0-- B--2- C--2- D0---
3855 42: A0-- B--2- C--2- D-1--
3856 43: A0-- B--2- C--2- D--2- -fcase-strict-lower
3857 44: A0-- B--2- C--2- D---3
3858 45: A0-- B--2- C---3 D0---
3859 46: A0-- B--2- C---3 D-1--
3860 47: A0-- B--2- C---3 D--2-
3861 48: A0-- B--2- C---3 D---3
3862 49: A0-- B---3 C0--- D0---
3863 50: A0-- B---3 C0--- D-1--
3864 51: A0-- B---3 C0--- D--2-
3865 52: A0-- B---3 C0--- D---3
3866 53: A0-- B---3 C-1-- D0---
3867 54: A0-- B---3 C-1-- D-1--
3868 55: A0-- B---3 C-1-- D--2-
3869 56: A0-- B---3 C-1-- D---3
3870 57: A0-- B---3 C--2- D0---
3871 58: A0-- B---3 C--2- D-1--
3872 59: A0-- B---3 C--2- D--2-
3873 60: A0-- B---3 C--2- D---3
3874 61: A0-- B---3 C---3 D0---
3875 62: A0-- B---3 C---3 D-1--
3876 63: A0-- B---3 C---3 D--2-
3877 64: A0-- B---3 C---3 D---3 -fcase-initcap
3878 65: A-1- B01-- C01-- D01-- -fcase-upper
3879 66: A--2 B0-2- C0-2- D0-2- -fcase-lower
3882 Number 22 is the ``strict'' ANSI FORTRAN 77 model wherein all input
3883 (except comments, character constants, and Hollerith strings) must
3884 be entered in uppercase.
3885 Use @option{-fcase-strict-upper} to specify this
3888 Number 43 is like Number 22 except all input must be lowercase. Use
3889 @option{-fcase-strict-lower} to specify this combination.
3891 Number 65 is the ``classic'' ANSI FORTRAN 77 model as implemented on many
3892 non-UNIX machines whereby all the source is translated to uppercase.
3893 Use @option{-fcase-upper} to specify this combination.
3895 Number 66 is the ``canonical'' UNIX model whereby all the source is
3896 translated to lowercase.
3897 Use @option{-fcase-lower} to specify this combination.
3899 There are a few nearly useless combinations:
3902 67: A-1- B01-- C01-- D--2-
3903 68: A-1- B01-- C01-- D---3
3904 69: A-1- B01-- C--23 D01--
3905 70: A-1- B01-- C--23 D--2-
3906 71: A-1- B01-- C--23 D---3
3907 72: A--2 B01-- C0-2- D-1--
3908 73: A--2 B01-- C0-2- D---3
3909 74: A--2 B01-- C-1-3 D0-2-
3910 75: A--2 B01-- C-1-3 D-1--
3911 76: A--2 B01-- C-1-3 D---3
3914 The above allow some programs to be compiled but with restrictions that
3915 make most useful programs impossible: Numbers 67 and 72 warn about
3916 @emph{any} user-defined symbol names (such as @samp{SUBROUTINE FOO});
3918 68 and 73 warn about any user-defined symbol names longer than one
3919 character that don't have at least one non-alphabetic character after
3921 Numbers 69 and 74 disallow any references to intrinsics;
3922 and Numbers 70, 71, 75, and 76 are combinations of the restrictions in
3923 67+69, 68+69, 72+74, and 73+74, respectively.
3925 All redundant combinations are shown in the above tables anyplace
3926 where more than one setting is shown for a low-level switch.
3927 For example, @samp{B0-2-} means either setting 0 or 2 is valid for switch B.
3928 The ``proper'' setting in such a case is the one that copies the setting
3929 of switch A---any other setting might slightly reduce the speed of
3930 the compiler, though possibly to an unmeasurable extent.
3932 All remaining combinations are useless in that they prevent successful
3933 compilation of non-null source files (source files with something other
3937 @section VXT Fortran
3939 @cindex VXT extensions
3940 @cindex extensions, VXT
3941 @command{g77} supports certain constructs that
3942 have different meanings in VXT Fortran than they
3943 do in the GNU Fortran language.
3945 Generally, this manual uses the invented term VXT Fortran to refer
3946 VAX FORTRAN (circa v4).
3947 That compiler offered many popular features, though not necessarily
3948 those that are specific to the VAX processor architecture,
3949 the VMS operating system,
3950 or Digital Equipment Corporation's Fortran product line.
3951 (VAX and VMS probably are trademarks of Digital Equipment
3954 An extension offered by a Digital Fortran product that also is
3955 offered by several other Fortran products for different kinds of
3956 systems is probably going to be considered for inclusion in @command{g77}
3957 someday, and is considered a VXT Fortran feature.
3959 The @option{-fvxt} option generally specifies that, where
3960 the meaning of a construct is ambiguous (means one thing
3961 in GNU Fortran and another in VXT Fortran), the VXT Fortran
3962 meaning is to be assumed.
3965 * Double Quote Meaning:: @samp{"2000} as octal constant.
3966 * Exclamation Point:: @samp{!} in column 6.
3969 @node Double Quote Meaning
3970 @subsection Meaning of Double Quote
3971 @cindex double quotes
3972 @cindex character constants
3973 @cindex constants, character
3974 @cindex octal constants
3975 @cindex constants, octal
3977 @command{g77} treats double-quote (@samp{"})
3978 as beginning an octal constant of @code{INTEGER(KIND=1)} type
3979 when the @option{-fvxt} option is specified.
3980 The form of this octal constant is
3987 where @var{octal-digits} is a nonempty string of characters in
3988 the set @samp{01234567}.
3990 For example, the @option{-fvxt} option permits this:
3998 The above program would print the value @samp{16}.
4000 @xref{Integer Type}, for information on the preferred construct
4001 for integer constants specified using GNU Fortran's octal notation.
4003 (In the GNU Fortran language, the double-quote character (@samp{"})
4004 delimits a character constant just as does apostrophe (@samp{'}).
4005 There is no way to allow
4006 both constructs in the general case, since statements like
4007 @samp{PRINT *,"2000 !comment?"} would be ambiguous.)
4009 @node Exclamation Point
4010 @subsection Meaning of Exclamation Point in Column 6
4012 @cindex exclamation point
4013 @cindex continuation character
4014 @cindex characters, continuation
4015 @cindex comment character
4016 @cindex characters, comment
4018 @command{g77} treats an exclamation point (@samp{!}) in column 6 of
4019 a fixed-form source file
4020 as a continuation character rather than
4021 as the beginning of a comment
4022 (as it does in any other column)
4023 when the @option{-fvxt} option is specified.
4025 The following program, when run, prints a message indicating
4026 whether it is interpreted according to GNU Fortran (and Fortran 90)
4027 rules or VXT Fortran rules:
4030 C234567 (This line begins in column 1.)
4033 IF (I.EQ.0) PRINT *, ' I am a VXT Fortran program'
4034 IF (I.EQ.1) PRINT *, ' I am a Fortran 90 program'
4035 IF (I.LT.0 .OR. I.GT.1) PRINT *, ' I am a HAL 9000 computer'
4039 (In the GNU Fortran and Fortran 90 languages, exclamation point is
4040 a valid character and, unlike space (@key{SPC}) or zero (@samp{0}),
4041 marks a line as a continuation line when it appears in column 6.)
4045 @cindex compatibility, Fortran 90
4046 @cindex Fortran 90, compatibility
4048 The GNU Fortran language includes a number of features that are
4049 part of Fortran 90, even when the @option{-ff90} option is not specified.
4050 The features enabled by @option{-ff90} are intended to be those that,
4051 when @option{-ff90} is not specified, would have another
4052 meaning to @command{g77}---usually meaning something invalid in the
4053 GNU Fortran language.
4055 So, the purpose of @option{-ff90} is not to specify whether @command{g77} is
4056 to gratuitously reject Fortran 90 constructs.
4057 The @option{-pedantic} option specified with @option{-fno-f90} is intended
4058 to do that, although its implementation is certainly incomplete at
4061 When @option{-ff90} is specified:
4065 The type of @samp{REAL(@var{expr})} and @samp{AIMAG(@var{expr})},
4066 where @var{expr} is @code{COMPLEX} type,
4067 is the same type as the real part of @var{expr}.
4069 For example, assuming @samp{Z} is type @code{COMPLEX(KIND=2)},
4070 @samp{REAL(Z)} would return a value of type @code{REAL(KIND=2)},
4071 not of type @code{REAL(KIND=1)}, since @option{-ff90} is specified.
4074 @node Pedantic Compilation
4075 @section Pedantic Compilation
4076 @cindex pedantic compilation
4077 @cindex compilation, pedantic
4079 The @option{-fpedantic} command-line option specifies that @command{g77}
4080 is to warn about code that is not standard-conforming.
4081 This is useful for finding
4082 some extensions @command{g77} accepts that other compilers might not accept.
4083 (Note that the @option{-pedantic} and @option{-pedantic-errors} options
4084 always imply @option{-fpedantic}.)
4086 With @option{-fno-f90} in force, ANSI FORTRAN 77 is used as the standard
4087 for conforming code.
4088 With @option{-ff90} in force, Fortran 90 is used.
4090 The constructs for which @command{g77} issues diagnostics when @option{-fpedantic}
4091 and @option{-fno-f90} are in force are:
4095 Automatic arrays, as in
4104 where @samp{A} is not listed in any @code{ENTRY} statement,
4105 and thus is not a dummy argument.
4108 The commas in @samp{READ (5), I} and @samp{WRITE (10), J}.
4110 These commas are disallowed by FORTRAN 77, but, while strictly
4111 superfluous, are syntactically elegant,
4112 especially given that commas are required in statements such
4113 as @samp{READ 99, I} and @samp{PRINT *, J}.
4114 Many compilers permit the superfluous commas for this reason.
4117 @code{DOUBLE COMPLEX}, either explicitly or implicitly.
4119 An explicit use of this type is via a @code{DOUBLE COMPLEX} or
4120 @code{IMPLICIT DOUBLE COMPLEX} statement, for examples.
4122 An example of an implicit use is the expression @samp{C*D},
4123 where @samp{C} is @code{COMPLEX(KIND=1)}
4124 and @samp{D} is @code{DOUBLE PRECISION}.
4125 This expression is prohibited by ANSI FORTRAN 77
4126 because the rules of promotion would suggest that it
4127 produce a @code{DOUBLE COMPLEX} result---a type not
4128 provided for by that standard.
4131 Automatic conversion of numeric
4132 expressions to @code{INTEGER(KIND=1)} in contexts such as:
4136 Array-reference indexes.
4138 Alternate-return values.
4140 Computed @code{GOTO}.
4142 @code{FORMAT} run-time expressions (not yet supported).
4144 Dimension lists in specification statements.
4146 Numbers for I/O statements (such as @samp{READ (UNIT=3.2), I})
4148 Sizes of @code{CHARACTER} entities in specification statements.
4150 Kind types in specification entities (a Fortran 90 feature).
4152 Initial, terminal, and incrementation parameters for implied-@code{DO}
4153 constructs in @code{DATA} statements.
4157 Automatic conversion of @code{LOGICAL} expressions to @code{INTEGER}
4158 in contexts such as arithmetic @code{IF} (where @code{COMPLEX}
4159 expressions are disallowed anyway).
4162 Zero-size array dimensions, as in:
4165 INTEGER I(10,20,4:2)
4169 Zero-length @code{CHARACTER} entities, as in:
4176 Substring operators applied to character constants and named
4180 PRINT *, 'hello'(3:5)
4184 Null arguments passed to statement function, as in:
4191 Disagreement among program units regarding whether a given @code{COMMON}
4192 area is @code{SAVE}d (for targets where program units in a single source
4193 file are ``glued'' together as they typically are for UNIX development
4197 Disagreement among program units regarding the size of a
4198 named @code{COMMON} block.
4201 Specification statements following first @code{DATA} statement.
4203 (In the GNU Fortran language, @samp{DATA I/1/} may be followed by @samp{INTEGER J},
4204 but not @samp{INTEGER I}.
4205 The @option{-fpedantic} option disallows both of these.)
4208 Semicolon as statement separator, as in:
4215 @c Comma before list of I/O items in @code{WRITE}
4216 @c @c, @code{ENCODE}, @code{DECODE}, and @code{REWRITE}
4217 @c statements, as with @code{READ} (as explained above).
4220 Use of @samp{&} in column 1 of fixed-form source (to indicate continuation).
4223 Use of @code{CHARACTER} constants to initialize numeric entities, and vice
4227 Expressions having two arithmetic operators in a row, such
4231 If @option{-fpedantic} is specified along with @option{-ff90}, the
4232 following constructs result in diagnostics:
4236 Use of semicolon as a statement separator on a line
4237 that has an @code{INCLUDE} directive.
4241 @section Distensions
4243 @cindex ugly features
4244 @cindex features, ugly
4246 The @option{-fugly-*} command-line options determine whether certain
4247 features supported by VAX FORTRAN and other such compilers, but considered
4248 too ugly to be in code that can be changed to use safer and/or more
4249 portable constructs, are accepted.
4250 These are humorously referred to as ``distensions'',
4251 extensions that just plain look ugly in the harsh light of day.
4254 * Ugly Implicit Argument Conversion:: Disabled via @option{-fno-ugly-args}.
4255 * Ugly Assumed-Size Arrays:: Enabled via @option{-fugly-assumed}.
4256 * Ugly Null Arguments:: Enabled via @option{-fugly-comma}.
4257 * Ugly Complex Part Extraction:: Enabled via @option{-fugly-complex}.
4258 * Ugly Conversion of Initializers:: Disabled via @option{-fno-ugly-init}.
4259 * Ugly Integer Conversions:: Enabled via @option{-fugly-logint}.
4260 * Ugly Assigned Labels:: Enabled via @option{-fugly-assign}.
4263 @node Ugly Implicit Argument Conversion
4264 @subsection Implicit Argument Conversion
4265 @cindex Hollerith constants
4266 @cindex constants, Hollerith
4268 The @option{-fno-ugly-args} option disables
4269 passing typeless and Hollerith constants as actual arguments
4270 in procedure invocations.
4279 These constructs can be too easily used to create non-portable
4280 code, but are not considered as ``ugly'' as others.
4281 Further, they are widely used in existing Fortran source code
4282 in ways that often are quite portable.
4283 Therefore, they are enabled by default.
4285 @node Ugly Assumed-Size Arrays
4286 @subsection Ugly Assumed-Size Arrays
4287 @cindex arrays, assumed-size
4288 @cindex assumed-size arrays
4289 @cindex DIMENSION X(1)
4291 The @option{-fugly-assumed} option enables
4292 the treatment of any array with a final dimension specified as @samp{1}
4293 as an assumed-size array, as if @samp{*} had been specified
4296 For example, @samp{DIMENSION X(1)} is treated as if it
4297 had read @samp{DIMENSION X(*)} if @samp{X} is listed as
4298 a dummy argument in a preceding @code{SUBROUTINE}, @code{FUNCTION},
4299 or @code{ENTRY} statement in the same program unit.
4301 Use an explicit lower bound to avoid this interpretation.
4302 For example, @samp{DIMENSION X(1:1)} is never treated as if
4303 it had read @samp{DIMENSION X(*)} or @samp{DIMENSION X(1:*)}.
4304 Nor is @samp{DIMENSION X(2-1)} affected by this option,
4305 since that kind of expression is unlikely to have been
4306 intended to designate an assumed-size array.
4308 This option is used to prevent warnings being issued about apparent
4309 out-of-bounds reference such as @samp{X(2) = 99}.
4311 It also prevents the array from being used in contexts that
4312 disallow assumed-size arrays, such as @samp{PRINT *,X}.
4313 In such cases, a diagnostic is generated and the source file is
4316 The construct affected by this option is used only in old code
4317 that pre-exists the widespread acceptance of adjustable and assumed-size
4318 arrays in the Fortran community.
4320 @emph{Note:} This option does not affect how @samp{DIMENSION X(1)} is
4321 treated if @samp{X} is listed as a dummy argument only
4322 @emph{after} the @code{DIMENSION} statement (presumably in
4323 an @code{ENTRY} statement).
4324 For example, @option{-fugly-assumed} has no effect on the
4325 following program unit:
4336 @node Ugly Complex Part Extraction
4337 @subsection Ugly Complex Part Extraction
4338 @cindex complex values
4340 @cindex imaginary part
4342 The @option{-fugly-complex} option enables
4343 use of the @code{REAL()} and @code{AIMAG()}
4344 intrinsics with arguments that are
4345 @code{COMPLEX} types other than @code{COMPLEX(KIND=1)}.
4347 With @option{-ff90} in effect, these intrinsics return
4348 the unconverted real and imaginary parts (respectively)
4351 With @option{-fno-f90} in effect, these intrinsics convert
4352 the real and imaginary parts to @code{REAL(KIND=1)}, and return
4353 the result of that conversion.
4355 Due to this ambiguity, the GNU Fortran language defines
4356 these constructs as invalid, except in the specific
4357 case where they are entirely and solely passed as an
4358 argument to an invocation of the @code{REAL()} intrinsic.
4366 is permitted even when @samp{Z} is @code{COMPLEX(KIND=2)}
4367 and @option{-fno-ugly-complex} is in effect, because the
4370 @command{g77} enforces this restriction, unless @option{-fugly-complex}
4371 is specified, in which case the appropriate interpretation is
4372 chosen and no diagnostic is issued.
4374 @xref{CMPAMBIG}, for information on how to cope with existing
4375 code with unclear expectations of @code{REAL()} and @code{AIMAG()}
4376 with @code{COMPLEX(KIND=2)} arguments.
4378 @xref{RealPart Intrinsic}, for information on the @code{REALPART()}
4379 intrinsic, used to extract the real part of a complex expression
4381 @xref{ImagPart Intrinsic}, for information on the @code{IMAGPART()}
4382 intrinsic, used to extract the imaginary part of a complex expression
4385 @node Ugly Null Arguments
4386 @subsection Ugly Null Arguments
4387 @cindex trailing comma
4388 @cindex comma, trailing
4389 @cindex characters, comma
4390 @cindex null arguments
4391 @cindex arguments, null
4393 The @option{-fugly-comma} option enables use of a single trailing comma
4394 to mean ``pass an extra trailing null argument''
4395 in a list of actual arguments to an external procedure,
4396 and use of an empty list of arguments to such a procedure
4397 to mean ``pass a single null argument''.
4399 @cindex omitting arguments
4400 @cindex arguments, omitting
4401 (Null arguments often are used in some procedure-calling
4402 schemes to indicate omitted arguments.)
4404 For example, @samp{CALL FOO(,)} means ``pass
4405 two null arguments'', rather than ``pass one null argument''.
4406 Also, @samp{CALL BAR()} means ``pass one null argument''.
4408 This construct is considered ``ugly'' because it does not
4409 provide an elegant way to pass a single null argument
4410 that is syntactically distinct from passing no arguments.
4411 That is, this construct changes the meaning of code that
4412 makes no use of the construct.
4414 So, with @option{-fugly-comma} in force, @samp{CALL FOO()}
4415 and @samp{I = JFUNC()} pass a single null argument, instead
4416 of passing no arguments as required by the Fortran 77 and
4419 @emph{Note:} Many systems gracefully allow the case
4420 where a procedure call passes one extra argument that the
4421 called procedure does not expect.
4423 So, in practice, there might be no difference in
4424 the behavior of a program that does @samp{CALL FOO()}
4425 or @samp{I = JFUNC()} and is compiled with @option{-fugly-comma}
4426 in force as compared to its behavior when compiled
4427 with the default, @option{-fno-ugly-comma}, in force,
4428 assuming @samp{FOO} and @samp{JFUNC} do not expect any
4429 arguments to be passed.
4431 @node Ugly Conversion of Initializers
4432 @subsection Ugly Conversion of Initializers
4434 The constructs disabled by @option{-fno-ugly-init} are:
4437 @cindex Hollerith constants
4438 @cindex constants, Hollerith
4440 Use of Hollerith and typeless constants in contexts where they set
4441 initial (compile-time) values for variables, arrays, and named
4442 constants---that is, @code{DATA} and @code{PARAMETER} statements, plus
4443 type-declaration statements specifying initial values.
4445 Here are some sample initializations that are disabled by the
4446 @option{-fno-ugly-init} option:
4449 PARAMETER (VAL='9A304FFE'X)
4450 REAL*8 STRING/8HOUTPUT00/
4454 @cindex character constants
4455 @cindex constants, character
4457 In the same contexts as above, use of character constants to initialize
4458 numeric items and vice versa (one constant per item).
4460 Here are more sample initializations that are disabled by the
4461 @option{-fno-ugly-init} option:
4466 PARAMETER (IA = 'A')
4467 PARAMETER (BELL = 7)
4471 Use of Hollerith and typeless constants on the right-hand side
4472 of assignment statements to numeric types, and in other
4473 contexts (such as passing arguments in invocations of
4474 intrinsic procedures and statement functions) that
4475 are treated as assignments to known types (the dummy
4476 arguments, in these cases).
4478 Here are sample statements that are disabled by the
4479 @option{-fno-ugly-init} option:
4483 PRINT *, IMAX0(2HAB, 2HBA)
4487 The above constructs, when used,
4488 can tend to result in non-portable code.
4489 But, they are widely used in existing Fortran code in ways
4490 that often are quite portable.
4491 Therefore, they are enabled by default.
4493 @node Ugly Integer Conversions
4494 @subsection Ugly Integer Conversions
4496 The constructs enabled via @option{-fugly-logint} are:
4500 Automatic conversion between @code{INTEGER} and @code{LOGICAL} as
4502 context (typically implies nonportable dependencies on how a
4503 particular implementation encodes @code{.TRUE.} and @code{.FALSE.}).
4506 Use of a @code{LOGICAL} variable in @code{ASSIGN} and assigned-@code{GOTO}
4510 The above constructs are disabled by default because use
4511 of them tends to lead to non-portable code.
4512 Even existing Fortran code that uses that often turns out
4513 to be non-portable, if not outright buggy.
4515 Some of this is due to differences among implementations as
4516 far as how @code{.TRUE.} and @code{.FALSE.} are encoded as
4517 @code{INTEGER} values---Fortran code that assumes a particular
4518 coding is likely to use one of the above constructs, and is
4519 also likely to not work correctly on implementations using
4520 different encodings.
4522 @xref{Equivalence Versus Equality}, for more information.
4524 @node Ugly Assigned Labels
4525 @subsection Ugly Assigned Labels
4526 @cindex ASSIGN statement
4527 @cindex statements, ASSIGN
4528 @cindex assigned labels
4531 The @option{-fugly-assign} option forces @command{g77} to use the
4532 same storage for assigned labels as it would for a normal
4533 assignment to the same variable.
4535 For example, consider the following code fragment:
4543 Normally, for portability and improved diagnostics, @command{g77}
4544 reserves distinct storage for a ``sibling'' of @samp{I}, used
4545 only for @code{ASSIGN} statements to that variable (along with
4546 the corresponding assigned-@code{GOTO} and assigned-@code{FORMAT}-I/O
4547 statements that reference the variable).
4549 However, some code (that violates the ANSI FORTRAN 77 standard)
4550 attempts to copy assigned labels among variables involved with
4551 @code{ASSIGN} statements, as in:
4562 Such code doesn't work under @command{g77} unless @option{-fugly-assign}
4563 is specified on the command-line, ensuring that the value of @code{I}
4564 referenced in the second line is whatever value @command{g77} uses
4565 to designate statement label @samp{10}, so the value may be
4566 copied into the @samp{ISTATE} array, later retrieved into a
4567 variable of the appropriate type (@samp{J}), and used as the target of
4568 an assigned-@code{GOTO} statement.
4570 @emph{Note:} To avoid subtle program bugs,
4571 when @option{-fugly-assign} is specified,
4572 @command{g77} requires the type of variables
4573 specified in assigned-label contexts
4574 @emph{must} be the same type returned by @code{%LOC()}.
4575 On many systems, this type is effectively the same
4576 as @code{INTEGER(KIND=1)}, while, on others, it is
4577 effectively the same as @code{INTEGER(KIND=2)}.
4579 Do @emph{not} depend on @command{g77} actually writing valid pointers
4580 to these variables, however.
4581 While @command{g77} currently chooses that implementation, it might
4582 be changed in the future.
4584 @xref{Assigned Statement Labels,,Assigned Statement Labels (ASSIGN and GOTO)},
4585 for implementation details on assigned-statement labels.
4588 @chapter The GNU Fortran Compiler
4590 The GNU Fortran compiler, @command{g77}, supports programs written
4591 in the GNU Fortran language and in some other dialects of Fortran.
4593 Some aspects of how @command{g77} works are universal regardless
4594 of dialect, and yet are not properly part of the GNU Fortran
4596 These are described below.
4598 @emph{Note: This portion of the documentation definitely needs a lot
4603 * Run-time Environment Limits::
4605 * Compiler Constants::
4606 * Compiler Intrinsics::
4609 @node Compiler Limits
4610 @section Compiler Limits
4611 @cindex limits, compiler
4612 @cindex compiler limits
4614 @command{g77}, as with GNU tools in general, imposes few arbitrary restrictions
4615 on lengths of identifiers, number of continuation lines, number of external
4616 symbols in a program, and so on.
4618 @cindex options, -Nl
4620 @cindex options, -Nx
4622 @cindex limits, continuation lines
4623 @cindex limits, lengths of names
4624 For example, some other Fortran compiler have an option
4625 (such as @option{-Nl@var{x}}) to increase the limit on the
4626 number of continuation lines.
4627 Also, some Fortran compilation systems have an option
4628 (such as @option{-Nx@var{x}}) to increase the limit on the
4629 number of external symbols.
4631 @command{g77}, @command{gcc}, and GNU @command{ld} (the GNU linker) have
4632 no equivalent options, since they do not impose arbitrary
4633 limits in these areas.
4635 @cindex rank, maximum
4636 @cindex maximum rank
4637 @cindex number of dimensions, maximum
4638 @cindex maximum number of dimensions
4639 @cindex limits, rank
4640 @cindex limits, array dimensions
4641 @command{g77} does currently limit the number of dimensions in an array
4642 to the same degree as do the Fortran standards---seven (7).
4643 This restriction might be lifted in a future version.
4645 @node Run-time Environment Limits
4646 @section Run-time Environment Limits
4647 @cindex limits, run-time library
4650 As a portable Fortran implementation,
4651 @command{g77} offers its users direct access to,
4652 and otherwise depends upon,
4653 the underlying facilities of the system
4654 used to build @command{g77},
4655 the system on which @command{g77} itself is used to compile programs,
4656 and the system on which the @command{g77}-compiled program is actually run.
4657 (For most users, the three systems are of the same
4658 type---combination of operating environment and hardware---often
4659 the same physical system.)
4661 The run-time environment for a particular system
4662 inevitably imposes some limits on a program's use
4663 of various system facilities.
4664 These limits vary from system to system.
4666 Even when such limits might be well beyond the
4667 possibility of being encountered on a particular system,
4668 the @command{g77} run-time environment
4669 has certain built-in limits,
4670 usually, but not always, stemming from intrinsics
4671 with inherently limited interfaces.
4673 Currently, the @command{g77} run-time environment
4674 does not generally offer a less-limiting environment
4675 by augmenting the underlying system's own environment.
4677 Therefore, code written in the GNU Fortran language,
4678 while syntactically and semantically portable,
4679 might nevertheless make non-portable assumptions
4680 about the run-time environment---assumptions that
4681 prove to be false for some particular environments.
4683 The GNU Fortran language,
4684 the @command{g77} compiler and run-time environment,
4685 and the @command{g77} documentation
4686 do not yet offer comprehensive portable work-arounds for such limits,
4687 though programmers should be able to
4688 find their own in specific instances.
4690 Not all of the limitations are described in this document.
4691 Some of the known limitations include:
4694 * Timer Wraparounds::
4695 * Year 2000 (Y2K) Problems::
4697 * Character-variable Length::
4698 * Year 10000 (Y10K) Problems::
4701 @node Timer Wraparounds
4702 @subsection Timer Wraparounds
4704 Intrinsics that return values computed from system timers,
4705 whether elapsed (wall-clock) timers,
4707 or other kinds of timers,
4708 are prone to experiencing wrap-around errors
4709 (or returning wrapped-around values from successive calls)
4710 due to insufficient ranges
4711 offered by the underlying system's timers.
4713 @cindex negative time
4716 Some of the symptoms of such behaviors include
4717 apparently negative time being computed for a duration,
4718 an extremely short amount of time being computed for a long duration,
4719 and an extremely long amount of time being computed for a short duration.
4721 See the following for intrinsics
4722 known to have potential problems in these areas
4723 on at least some systems:
4724 @ref{CPU_Time Intrinsic},
4725 @ref{DTime Intrinsic (function)}, @ref{DTime Intrinsic (subroutine)},
4726 @ref{ETime Intrinsic (function)}, @ref{ETime Intrinsic (subroutine)},
4727 @ref{MClock Intrinsic}, @ref{MClock8 Intrinsic},
4728 @ref{Secnds Intrinsic},
4729 @ref{Second Intrinsic (function)}, @ref{Second Intrinsic (subroutine)},
4730 @ref{System_Clock Intrinsic},
4731 @ref{Time Intrinsic (UNIX)}, @ref{Time Intrinsic (VXT)},
4732 @ref{Time8 Intrinsic}.
4734 @node Year 2000 (Y2K) Problems
4735 @subsection Year 2000 (Y2K) Problems
4736 @cindex Y2K compliance
4737 @cindex Year 2000 compliance
4739 While the @command{g77} compiler itself is believed to
4740 be Year-2000 (Y2K) compliant,
4741 some intrinsics are not,
4742 and, potentially, some underlying systems are not,
4743 perhaps rendering some Y2K-compliant intrinsics
4744 non-compliant when used on those particular systems.
4746 Fortran code that uses non-Y2K-compliant intrinsics
4748 is, itself, almost certainly not compliant,
4749 and should be modified to use Y2K-compliant intrinsics instead.
4751 Fortran code that uses no non-Y2K-compliant intrinsics,
4752 but which currently is running on a non-Y2K-compliant system,
4753 can be made more Y2K compliant by compiling and
4754 linking it for use on a new Y2K-compliant system,
4755 such as a new version of an old, non-Y2K-compliant, system.
4757 Currently, information on Y2K and related issues
4758 is being maintained at
4759 @uref{http://www.gnu.org/software/year2000-list.html}.
4761 See the following for intrinsics
4762 known to have potential problems in these areas
4763 on at least some systems:
4764 @ref{Date Intrinsic},
4765 @ref{IDate Intrinsic (VXT)}.
4768 @cindex date_y2kbuggy_0
4769 @cindex vxtidate_y2kbuggy_0
4770 @cindex G77_date_y2kbuggy_0
4771 @cindex G77_vxtidate_y2kbuggy_0
4772 The @code{libg2c} library
4773 shipped with any @command{g77} that warns
4774 about invocation of a non-Y2K-compliant intrinsic
4775 has renamed the @code{EXTERNAL} procedure names
4776 of those intrinsics.
4777 This is done so that
4778 the @code{libg2c} implementations of these intrinsics
4779 cannot be directly linked to
4780 as @code{EXTERNAL} names
4781 (which normally would avoid the non-Y2K-intrinsic warning).
4783 The renamed forms of the @code{EXTERNAL} names
4784 of these renamed procedures
4786 by appending the string @samp{_y2kbug}
4787 to the name of the procedure
4794 EXTERNAL DATE_Y2KBUG, VXTIDATE_Y2KBUG
4795 CALL DATE_Y2KBUG (STR)
4796 CALL VXTIDATE_Y2KBUG (MM, DD, YY)
4799 (Note that the @code{EXTERNAL} statement
4800 is not actually required,
4801 since the modified names are not recognized as intrinsics
4802 by the current version of @command{g77}.
4803 But it is shown in this specific case,
4804 for purposes of illustration.)
4806 The renaming of @code{EXTERNAL} procedure names of these intrinsics
4807 causes unresolved references at link time.
4808 For example, @samp{EXTERNAL DATE; CALL DATE(STR)}
4809 is normally compiled by @command{g77}
4810 as, in C, @samp{date_(&str, 20);}.
4811 This, in turn, links to the @code{date_} procedure
4812 in the @code{libE77} portion of @code{libg2c},
4813 which purposely calls a nonexistent procedure
4814 named @code{G77_date_y2kbuggy_0}.
4815 The resulting link-time error is designed, via this name,
4816 to encourage the programmer to look up the
4817 index entries to this portion of the @command{g77} documentation.
4819 Generally, we recommend that the @code{EXTERNAL} method
4820 of invoking procedures in @code{libg2c}
4822 When used, some of the correctness checking
4823 normally performed by @command{g77}
4826 In particular, it is probably better to use the
4827 @code{INTRINSIC} method of invoking
4828 non-Y2K-compliant procedures,
4829 so anyone compiling the code
4830 can quickly notice the potential Y2K problems
4831 (via the warnings printing by @command{g77})
4832 without having to even look at the code itself.
4834 If there are problems linking @code{libg2c}
4835 to code compiled by @command{g77}
4836 that involve the string @samp{y2kbug},
4837 and these are not explained above,
4838 that probably indicates
4839 that a version of @code{libg2c}
4840 older than @command{g77}
4842 or that the new library is being linked
4843 to code compiled by an older version of @command{g77}.
4845 That's because, as of the version that warns about
4846 non-Y2K-compliant intrinsic invocation,
4847 @command{g77} references the @code{libg2c} implementations
4849 using new names, containing the string @samp{y2kbug}.
4851 So, linking newly-compiled code
4852 (invoking one of the intrinsics in question)
4854 might yield an unresolved reference
4855 to @code{G77_date_y2kbug_0}.
4856 (The old library calls it @code{G77_date_0}.)
4858 Similarly, linking previously-compiled code
4860 might yield an unresolved reference
4861 to @code{G77_vxtidate_0}.
4862 (The new library calls it @code{G77_vxtidate_y2kbug_0}.)
4864 The proper fix for the above problems
4865 is to obtain the latest release of @command{g77}
4866 and related products
4867 (including @code{libg2c})
4868 and install them on all systems,
4869 then recompile, relink, and install
4871 all existing Fortran programs.
4873 (Normally, this sort of renaming is steadfastly avoided.
4874 In this case, however, it seems more important to highlight
4875 potential Y2K problems
4876 than to ease the transition
4877 of potentially non-Y2K-compliant code
4878 to new versions of @command{g77} and @code{libg2c}.)
4881 @subsection Array Size
4882 @cindex limits, array size
4885 Currently, @command{g77} uses the default @code{INTEGER} type
4887 which limits the sizes of single-dimension arrays
4888 on systems offering a larger address space
4889 than can be addressed by that type.
4890 (That @command{g77} puts all arrays in memory
4891 could be considered another limitation---it
4892 could use large temporary files---but that decision
4893 is left to the programmer as an implementation choice
4894 by most Fortran implementations.)
4896 @c ??? Investigate this, to offer a more clear statement
4897 @c than the following paragraphs do. -- burley 1999-02-17
4898 It is not yet clear whether this limitation
4899 never, sometimes, or always applies to the
4900 sizes of multiple-dimension arrays as a whole.
4902 For example, on a system with 64-bit addresses
4903 and 32-bit default @code{INTEGER},
4904 an array with a size greater than can be addressed
4906 can be declared using multiple dimensions.
4907 Such an array is therefore larger
4908 than a single-dimension array can be,
4911 @cindex limits, multi-dimension arrays
4912 @cindex multi-dimension arrays
4913 @cindex arrays, dimensioning
4914 Whether large multiple-dimension arrays are reliably supported
4915 depends mostly on the @command{gcc} back end (code generator)
4916 used by @command{g77}, and has not yet been fully investigated.
4918 @node Character-variable Length
4919 @subsection Character-variable Length
4920 @cindex limits, on character-variable length
4921 @cindex character-variable length
4923 Currently, @command{g77} uses the default @code{INTEGER} type
4924 for the lengths of @code{CHARACTER} variables
4927 This means that, for example,
4928 a system with a 64-bit address space
4929 and a 32-bit default @code{INTEGER} type
4930 does not, under @command{g77},
4931 support a @code{CHARACTER*@var{n}} declaration
4932 where @var{n} is greater than 2147483647.
4934 @node Year 10000 (Y10K) Problems
4935 @subsection Year 10000 (Y10K) Problems
4936 @cindex Y10K compliance
4937 @cindex Year 10000 compliance
4939 Most intrinsics returning, or computing values based on,
4940 date information are prone to Year-10000 (Y10K) problems,
4941 due to supporting only 4 digits for the year.
4943 See the following for examples:
4944 @ref{FDate Intrinsic (function)}, @ref{FDate Intrinsic (subroutine)},
4945 @ref{IDate Intrinsic (UNIX)},
4946 @ref{Time Intrinsic (VXT)},
4947 @ref{Date_and_Time Intrinsic}.
4949 @node Compiler Types
4950 @section Compiler Types
4951 @cindex types, of data
4954 Fortran implementations have a fair amount of freedom given them by the
4955 standard as far as how much storage space is used and how much precision
4956 and range is offered by the various types such as @code{LOGICAL(KIND=1)},
4957 @code{INTEGER(KIND=1)}, @code{REAL(KIND=1)}, @code{REAL(KIND=2)},
4958 @code{COMPLEX(KIND=1)}, and @code{CHARACTER}.
4959 Further, many compilers offer so-called @samp{*@var{n}} notation, but
4960 the interpretation of @var{n} varies across compilers and target architectures.
4962 The standard requires that @code{LOGICAL(KIND=1)}, @code{INTEGER(KIND=1)},
4963 and @code{REAL(KIND=1)}
4964 occupy the same amount of storage space, and that @code{COMPLEX(KIND=1)}
4965 and @code{REAL(KIND=2)} take twice as much storage space as @code{REAL(KIND=1)}.
4966 Further, it requires that @code{COMPLEX(KIND=1)}
4967 entities be ordered such that when a @code{COMPLEX(KIND=1)} variable is
4968 storage-associated (such as via @code{EQUIVALENCE})
4969 with a two-element @code{REAL(KIND=1)} array named @samp{R}, @samp{R(1)}
4970 corresponds to the real element and @samp{R(2)} to the imaginary
4971 element of the @code{COMPLEX(KIND=1)} variable.
4973 (Few requirements as to precision or ranges of any of these are
4974 placed on the implementation, nor is the relationship of storage sizes of
4975 these types to the @code{CHARACTER} type specified, by the standard.)
4977 @command{g77} follows the above requirements, warning when compiling
4978 a program requires placement of items in memory that contradict the
4979 requirements of the target architecture.
4980 (For example, a program can require placement of a @code{REAL(KIND=2)}
4981 on a boundary that is not an even multiple of its size, but still an
4982 even multiple of the size of a @code{REAL(KIND=1)} variable.
4983 On some target architectures, using the canonical
4984 mapping of Fortran types to underlying architectural types, such
4985 placement is prohibited by the machine definition or
4986 the Application Binary Interface (ABI) in force for
4987 the configuration defined for building @command{gcc} and @command{g77}.
4988 @command{g77} warns about such
4989 situations when it encounters them.)
4991 @command{g77} follows consistent rules for configuring the mapping between Fortran
4992 types, including the @samp{*@var{n}} notation, and the underlying architectural
4993 types as accessed by a similarly-configured applicable version of the
4994 @command{gcc} compiler.
4995 These rules offer a widely portable, consistent Fortran/C
4996 environment, although they might well conflict with the expectations of
4997 users of Fortran compilers designed and written for particular
5000 These rules are based on the configuration that is in force for the
5001 version of @command{gcc} built in the same release as @command{g77} (and
5002 which was therefore used to build both the @command{g77} compiler
5003 components and the @code{libg2c} run-time library):
5006 @cindex REAL(KIND=1) type
5007 @cindex types, REAL(KIND=1)
5009 Same as @code{float} type.
5011 @cindex REAL(KIND=2) type
5012 @cindex types, REAL(KIND=2)
5014 Same as whatever floating-point type that is twice the size
5015 of a @code{float}---usually, this is a @code{double}.
5017 @cindex INTEGER(KIND=1) type
5018 @cindex types, INTEGER(KIND=1)
5019 @item INTEGER(KIND=1)
5020 Same as an integral type that is occupies the same amount
5021 of memory storage as @code{float}---usually, this is either
5022 an @code{int} or a @code{long int}.
5024 @cindex LOGICAL(KIND=1) type
5025 @cindex types, LOGICAL(KIND=1)
5026 @item LOGICAL(KIND=1)
5027 Same @command{gcc} type as @code{INTEGER(KIND=1)}.
5029 @cindex INTEGER(KIND=2) type
5030 @cindex types, INTEGER(KIND=2)
5031 @item INTEGER(KIND=2)
5032 Twice the size, and usually nearly twice the range,
5033 as @code{INTEGER(KIND=1)}---usually, this is either
5034 a @code{long int} or a @code{long long int}.
5036 @cindex LOGICAL(KIND=2) type
5037 @cindex types, LOGICAL(KIND=2)
5038 @item LOGICAL(KIND=2)
5039 Same @command{gcc} type as @code{INTEGER(KIND=2)}.
5041 @cindex INTEGER(KIND=3) type
5042 @cindex types, INTEGER(KIND=3)
5043 @item INTEGER(KIND=3)
5044 Same @command{gcc} type as signed @code{char}.
5046 @cindex LOGICAL(KIND=3) type
5047 @cindex types, LOGICAL(KIND=3)
5048 @item LOGICAL(KIND=3)
5049 Same @command{gcc} type as @code{INTEGER(KIND=3)}.
5051 @cindex INTEGER(KIND=6) type
5052 @cindex types, INTEGER(KIND=6)
5053 @item INTEGER(KIND=6)
5054 Twice the size, and usually nearly twice the range,
5055 as @code{INTEGER(KIND=3)}---usually, this is
5058 @cindex LOGICAL(KIND=6) type
5059 @cindex types, LOGICAL(KIND=6)
5060 @item LOGICAL(KIND=6)
5061 Same @command{gcc} type as @code{INTEGER(KIND=6)}.
5063 @cindex COMPLEX(KIND=1) type
5064 @cindex types, COMPLEX(KIND=1)
5065 @item COMPLEX(KIND=1)
5066 Two @code{REAL(KIND=1)} scalars (one for the real part followed by
5067 one for the imaginary part).
5069 @cindex COMPLEX(KIND=2) type
5070 @cindex types, COMPLEX(KIND=2)
5071 @item COMPLEX(KIND=2)
5072 Two @code{REAL(KIND=2)} scalars.
5074 @cindex *@var{n} notation
5075 @item @var{numeric-type}*@var{n}
5076 (Where @var{numeric-type} is any type other than @code{CHARACTER}.)
5077 Same as whatever @command{gcc} type occupies @var{n} times the storage
5078 space of a @command{gcc} @code{char} item.
5080 @cindex DOUBLE PRECISION type
5081 @cindex types, DOUBLE PRECISION
5082 @item DOUBLE PRECISION
5083 Same as @code{REAL(KIND=2)}.
5085 @cindex DOUBLE COMPLEX type
5086 @cindex types, DOUBLE COMPLEX
5087 @item DOUBLE COMPLEX
5088 Same as @code{COMPLEX(KIND=2)}.
5091 Note that the above are proposed correspondences and might change
5092 in future versions of @command{g77}---avoid writing code depending
5095 Other types supported by @command{g77}
5096 are derived from gcc types such as @code{char}, @code{short},
5097 @code{int}, @code{long int}, @code{long long int}, @code{long double},
5099 That is, whatever types @command{gcc} already supports, @command{g77} supports
5100 now or probably will support in a future version.
5101 The rules for the @samp{@var{numeric-type}*@var{n}} notation
5102 apply to these types,
5103 and new values for @samp{@var{numeric-type}(KIND=@var{n})} will be
5104 assigned in a way that encourages clarity, consistency, and portability.
5106 @node Compiler Constants
5107 @section Compiler Constants
5109 @cindex types, constants
5111 @command{g77} strictly assigns types to @emph{all} constants not
5112 documented as ``typeless'' (typeless constants including @samp{'1'Z},
5114 Many other Fortran compilers attempt to assign types to typed constants
5115 based on their context.
5116 This results in hard-to-find bugs, nonportable
5117 code, and is not in the spirit (though it strictly follows the letter)
5118 of the 77 and 90 standards.
5120 @command{g77} might offer, in a future release, explicit constructs by
5121 which a wider variety of typeless constants may be specified, and/or
5122 user-requested warnings indicating places where @command{g77} might differ
5123 from how other compilers assign types to constants.
5125 @xref{Context-Sensitive Constants}, for more information on this issue.
5127 @node Compiler Intrinsics
5128 @section Compiler Intrinsics
5130 @command{g77} offers an ever-widening set of intrinsics.
5131 Currently these all are procedures (functions and subroutines).
5133 Some of these intrinsics are unimplemented, but their names reserved
5134 to reduce future problems with existing code as they are implemented.
5135 Others are implemented as part of the GNU Fortran language, while
5136 yet others are provided for compatibility with other dialects of
5137 Fortran but are not part of the GNU Fortran language.
5139 To manage these distinctions, @command{g77} provides intrinsic @emph{groups},
5140 a facility that is simply an extension of the intrinsic groups provided
5141 by the GNU Fortran language.
5144 * Intrinsic Groups:: How intrinsics are grouped for easy management.
5145 * Other Intrinsics:: Intrinsics other than those in the GNU
5149 @node Intrinsic Groups
5150 @subsection Intrinsic Groups
5151 @cindex groups of intrinsics
5152 @cindex intrinsics, groups
5154 A given specific intrinsic belongs in one or more groups.
5155 Each group is deleted, disabled, hidden, or enabled
5156 by default or a command-line option.
5157 The meaning of each term follows.
5160 @cindex deleted intrinsics
5161 @cindex intrinsics, deleted
5163 No intrinsics are recognized as belonging to that group.
5165 @cindex disabled intrinsics
5166 @cindex intrinsics, disabled
5168 Intrinsics are recognized as belonging to the group, but
5169 references to them (other than via the @code{INTRINSIC} statement)
5170 are disallowed through that group.
5172 @cindex hidden intrinsics
5173 @cindex intrinsics, hidden
5175 Intrinsics in that group are recognized and enabled (if implemented)
5176 @emph{only} if the first mention of the actual name of an intrinsic
5177 in a program unit is in an @code{INTRINSIC} statement.
5179 @cindex enabled intrinsics
5180 @cindex intrinsics, enabled
5182 Intrinsics in that group are recognized and enabled (if implemented).
5185 The distinction between deleting and disabling a group is illustrated
5186 by the following example.
5187 Assume intrinsic @samp{FOO} belongs only to group @samp{FGR}.
5188 If group @samp{FGR} is deleted, the following program unit will
5189 successfully compile, because @samp{FOO()} will be seen as a
5190 reference to an external function named @samp{FOO}:
5198 If group @samp{FGR} is disabled, compiling the above program will produce
5199 diagnostics, either because the @samp{FOO} intrinsic is improperly invoked
5200 or, if properly invoked, it is not enabled.
5201 To change the above program so it references an external function @samp{FOO}
5202 instead of the disabled @samp{FOO} intrinsic,
5203 add the following line to the top:
5210 So, deleting a group tells @command{g77} to pretend as though the intrinsics in
5211 that group do not exist at all, whereas disabling it tells @command{g77} to
5212 recognize them as (disabled) intrinsics in intrinsic-like contexts.
5214 Hiding a group is like enabling it, but the intrinsic must be first
5215 named in an @code{INTRINSIC} statement to be considered a reference to the
5216 intrinsic rather than to an external procedure.
5217 This might be the ``safest'' way to treat a new group of intrinsics
5219 code, because it allows the old code to be generally written as if
5220 those new intrinsics never existed, but to be changed to use them
5221 by inserting @code{INTRINSIC} statements in the appropriate places.
5222 However, it should be the goal of development to use @code{EXTERNAL}
5223 for all names of external procedures that might be intrinsic names.
5225 If an intrinsic is in more than one group, it is enabled if any of its
5226 containing groups are enabled; if not so enabled, it is hidden if
5227 any of its containing groups are hidden; if not so hidden, it is disabled
5228 if any of its containing groups are disabled; if not so disabled, it is
5230 This extra complication is necessary because some intrinsics,
5231 such as @code{IBITS}, belong to more than one group, and hence should be
5232 enabled if any of the groups to which they belong are enabled, and so
5237 @cindex intrinsics, groups of
5238 @cindex groups of intrinsics
5240 @cindex @code{badu77} intrinsics group
5242 UNIX intrinsics having inappropriate forms (usually functions that
5243 have intended side effects).
5245 @cindex @code{gnu} intrinsics group
5247 Intrinsics the GNU Fortran language supports that are extensions to
5248 the Fortran standards (77 and 90).
5250 @cindex @command{f2c} intrinsics group
5252 Intrinsics supported by AT&T's @command{f2c} converter and/or @code{libf2c}.
5254 @cindex @code{f90} intrinsics group
5256 Fortran 90 intrinsics.
5258 @cindex @code{mil} intrinsics group
5260 MIL-STD 1753 intrinsics (@code{MVBITS}, @code{IAND}, @code{BTEST}, and so on).
5262 @cindex @code{mil} intrinsics group
5264 UNIX intrinsics (@code{IARGC}, @code{EXIT}, @code{ERF}, and so on).
5266 @cindex @code{mil} intrinsics group
5268 VAX/VMS FORTRAN (current as of v4) intrinsics.
5271 @node Other Intrinsics
5272 @subsection Other Intrinsics
5273 @cindex intrinsics, others
5274 @cindex other intrinsics
5276 @command{g77} supports intrinsics other than those in the GNU Fortran
5278 This set of intrinsics is described below.
5281 (Note that the empty lines appearing in the menu below
5282 are not intentional---they result from a bug in the
5283 @code{makeinfo} program.)
5286 @c The actual documentation for intrinsics comes from
5287 @c intdoc.texi, which in turn is automatically generated
5288 @c from the internal g77 tables in intrin.def _and_ the
5289 @c largely hand-written text in intdoc.h. So, if you want
5290 @c to change or add to existing documentation on intrinsics,
5291 @c you probably want to edit intdoc.h.
5303 @include intdoc.texi
5305 @node Other Compilers
5306 @chapter Other Compilers
5308 An individual Fortran source file can be compiled to
5309 an object (@file{*.o}) file instead of to the final
5311 This allows several portions of a program to be compiled
5312 at different times and linked together whenever a new
5313 version of the program is needed.
5314 However, it introduces the issue of @dfn{object compatibility}
5315 across the various object files (and libraries, or @file{*.a}
5316 files) that are linked together to produce any particular
5319 Object compatibility is an issue when combining, in one
5320 program, Fortran code compiled by more than one compiler
5321 (or more than one configuration of a compiler).
5323 disagree on how to transform the names of procedures, there
5324 will normally be errors when linking such programs.
5325 Worse, if the compilers agree on naming, but disagree on issues
5326 like how to pass parameters, return arguments, and lay out
5327 @code{COMMON} areas, the earliest detected errors might be the
5328 incorrect results produced by the program (and that assumes
5329 these errors are detected, which is not always the case).
5331 Normally, @command{g77} generates code that is
5332 object-compatible with code generated by a version of
5333 @command{f2c} configured (with, for example, @file{f2c.h} definitions)
5334 to be generally compatible with @command{g77} as built by @command{gcc}.
5335 (Normally, @command{f2c} will, by default, conform to the appropriate
5336 configuration, but it is possible that older or perhaps even newer
5337 versions of @command{f2c}, or versions having certain configuration changes
5338 to @command{f2c} internals, will produce object files that are
5339 incompatible with @command{g77}.)
5341 For example, a Fortran string subroutine
5342 argument will become two arguments on the C side: a @code{char *}
5343 and an @code{int} length.
5345 Much of this compatibility results from the fact that
5346 @command{g77} uses the same run-time library,
5347 @code{libf2c}, used by @command{f2c},
5348 though @command{g77} gives its version the name @code{libg2c}
5349 so as to avoid conflicts when linking,
5350 installing them in the same directories,
5353 Other compilers might or might not generate code that
5354 is object-compatible with @code{libg2c} and current @command{g77},
5355 and some might offer such compatibility only when explicitly
5356 selected via a command-line option to the compiler.
5358 @emph{Note: This portion of the documentation definitely needs a lot
5362 * Dropping f2c Compatibility:: When speed is more important.
5363 * Compilers Other Than f2c:: Interoperation with code from other compilers.
5366 @node Dropping f2c Compatibility
5367 @section Dropping @command{f2c} Compatibility
5369 Specifying @option{-fno-f2c} allows @command{g77} to generate, in
5370 some cases, faster code, by not needing to allow to the possibility
5371 of linking with code compiled by @command{f2c}.
5373 For example, this affects how @code{REAL(KIND=1)},
5374 @code{COMPLEX(KIND=1)}, and @code{COMPLEX(KIND=2)} functions are called.
5375 With @option{-fno-f2c}, they are
5376 compiled as returning the appropriate @command{gcc} type
5377 (@code{float}, @code{__complex__ float}, @code{__complex__ double},
5378 in many configurations).
5380 With @option{-ff2c} in force, they
5381 are compiled differently (with perhaps slower run-time performance)
5382 to accommodate the restrictions inherent in @command{f2c}'s use of K&R
5383 C as an intermediate language---@code{REAL(KIND=1)} functions
5384 return C's @code{double} type, while @code{COMPLEX} functions return
5385 @code{void} and use an extra argument pointing to a place for the functions to
5386 return their values.
5388 It is possible that, in some cases, leaving @option{-ff2c} in force
5389 might produce faster code than using @option{-fno-f2c}.
5390 Feel free to experiment, but remember to experiment with changing the way
5391 @emph{entire programs and their Fortran libraries are compiled} at
5392 a time, since this sort of experimentation affects the interface
5393 of code generated for a Fortran source file---that is, it affects
5394 object compatibility.
5396 Note that @command{f2c} compatibility is a fairly static target to achieve,
5397 though not necessarily perfectly so, since, like @command{g77}, it is
5398 still being improved.
5399 However, specifying @option{-fno-f2c} causes @command{g77}
5400 to generate code that will probably be incompatible with code
5401 generated by future versions of @command{g77} when the same option
5403 You should make sure you are always able to recompile complete
5404 programs from source code when upgrading to new versions of @command{g77}
5405 or @command{f2c}, especially when using options such as @option{-fno-f2c}.
5407 Therefore, if you are using @command{g77} to compile libraries and other
5408 object files for possible future use and you don't want to require
5409 recompilation for future use with subsequent versions of @command{g77},
5410 you might want to stick with @command{f2c} compatibility for now, and
5411 carefully watch for any announcements about changes to the
5412 @command{f2c}/@code{libf2c} interface that might affect existing programs
5413 (thus requiring recompilation).
5415 It is probable that a future version of @command{g77} will not,
5416 by default, generate object files compatible with @command{f2c},
5417 and that version probably would no longer use @code{libf2c}.
5418 If you expect to depend on this compatibility in the
5419 long term, use the options @samp{-ff2c -ff2c-library} when compiling
5420 all of the applicable code.
5421 This should cause future versions of @command{g77} either to produce
5422 compatible code (at the expense of the availability of some features and
5423 performance), or at the very least, to produce diagnostics.
5425 (The library @command{g77} produces will no longer be named @file{libg2c}
5426 when it is no longer generally compatible with @file{libf2c}.
5427 It will likely be referred to, and, if installed as a distinct
5428 library, named @code{libg77}, or some other as-yet-unused name.)
5430 @node Compilers Other Than f2c
5431 @section Compilers Other Than @command{f2c}
5433 On systems with Fortran compilers other than @command{f2c} and @command{g77},
5434 code compiled by @command{g77} is not expected to work
5435 well with code compiled by the native compiler.
5436 (This is true for @command{f2c}-compiled objects as well.)
5437 Libraries compiled with the native compiler probably will have
5438 to be recompiled with @command{g77} to be used with @command{g77}-compiled code.
5440 Reasons for such incompatibilities include:
5444 There might be differences in the way names of Fortran procedures
5445 are translated for use in the system's object-file format.
5446 For example, the statement @samp{CALL FOO} might be compiled
5447 by @command{g77} to call a procedure the linker @command{ld} sees
5448 given the name @samp{_foo_}, while the apparently corresponding
5449 statement @samp{SUBROUTINE FOO} might be compiled by the
5450 native compiler to define the linker-visible name @samp{_foo},
5451 or @samp{_FOO_}, and so on.
5454 There might be subtle type mismatches which cause subroutine arguments
5455 and function return values to get corrupted.
5457 This is why simply getting @command{g77} to
5458 transform procedure names the same way a native
5459 compiler does is not usually a good idea---unless
5460 some effort has been made to ensure that, aside
5461 from the way the two compilers transform procedure
5462 names, everything else about the way they generate
5463 code for procedure interfaces is identical.
5467 use libraries of private I/O routines which will not be available
5468 at link time unless you have the native compiler---and you would
5469 have to explicitly ask for them.
5471 For example, on the Sun you
5472 would have to add @samp{-L/usr/lang/SCx.x -lF77 -lV77} to the link
5476 @node Other Languages
5477 @chapter Other Languages
5479 @emph{Note: This portion of the documentation definitely needs a lot
5483 * Interoperating with C and C++::
5486 @node Interoperating with C and C++
5487 @section Tools and advice for interoperating with C and C++
5489 @cindex C, linking with
5490 @cindex C++, linking with
5491 @cindex linking with C
5492 The following discussion assumes that you are running @command{g77} in @command{f2c}
5493 compatibility mode, i.e.@: not using @option{-fno-f2c}.
5495 advice about quick and simple techniques for linking Fortran and C (or
5496 C++), the most common requirement.
5497 For the full story consult the
5498 description of code generation.
5499 @xref{Debugging and Interfacing}.
5501 When linking Fortran and C, it's usually best to use @command{g77} to do
5502 the linking so that the correct libraries are included (including the
5504 If you're linking with C++ you will want to add
5505 @option{-lstdc++}, @option{-lg++} or whatever.
5506 If you need to use another
5507 driver program (or @command{ld} directly),
5508 you can find out what linkage
5509 options @command{g77} passes by running @samp{g77 -v}.
5512 * C Interfacing Tools::
5513 * C Access to Type Information::
5514 * f2c Skeletons and Prototypes::
5515 * C++ Considerations::
5519 @node C Interfacing Tools
5520 @subsection C Interfacing Tools
5524 Even if you don't actually use it as a compiler, @command{f2c} from
5525 @uref{ftp://ftp.netlib.org/f2c/src}, can be a useful tool when you're
5526 interfacing (linking) Fortran and C@.
5527 @xref{f2c Skeletons and Prototypes,,Generating Skeletons and Prototypes with @command{f2c}}.
5529 To use @command{f2c} for this purpose you only need retrieve and
5530 build the @file{src} directory from the distribution, consult the
5531 @file{README} instructions there for machine-specifics, and install the
5532 @command{f2c} program on your path.
5534 Something else that might be useful is @samp{cfortran.h} from
5535 @uref{ftp://zebra.desy.de/cfortran}.
5536 This is a fairly general tool which
5537 can be used to generate interfaces for calling in both directions
5538 between Fortran and C@.
5539 It can be used in @command{f2c} mode with
5540 @command{g77}---consult its documentation for details.
5542 @node C Access to Type Information
5543 @subsection Accessing Type Information in C
5545 @cindex types, Fortran/C
5546 Generally, C code written to link with
5547 @command{g77} code---calling and/or being
5548 called from Fortran---should @samp{#include <g2c.h>} to define the C
5549 versions of the Fortran types.
5550 Don't assume Fortran @code{INTEGER} types
5551 correspond to C @code{int}s, for instance; instead, declare them as
5552 @code{integer}, a type defined by @file{g2c.h}.
5553 @file{g2c.h} is installed where @command{gcc} will find it by
5554 default, assuming you use a copy of @command{gcc} compatible with
5555 @command{g77}, probably built at the same time as @command{g77}.
5557 @node f2c Skeletons and Prototypes
5558 @subsection Generating Skeletons and Prototypes with @command{f2c}
5561 @cindex -fno-second-underscore
5562 A simple and foolproof way to write @command{g77}-callable C routines---e.g.@: to
5563 interface with an existing library---is to write a file (named, for
5564 example, @file{fred.f}) of dummy Fortran
5565 skeletons comprising just the declaration of the routine(s) and dummy
5566 arguments plus @code{END} statements.
5567 Then run @command{f2c} on file @file{fred.f} to produce @file{fred.c}
5568 into which you can edit
5569 useful code, confident the calling sequence is correct, at least.
5570 (There are some errors otherwise commonly made in generating C
5571 interfaces with @command{f2c} conventions,
5572 such as not using @code{doublereal}
5573 as the return type of a @code{REAL} @code{FUNCTION}.)
5576 @command{f2c} also can help with calling Fortran from C, using its
5577 @option{-P} option to generate C prototypes appropriate for calling the
5578 Fortran.@footnote{The files generated like this can also be used for
5579 inter-unit consistency checking of dummy and actual arguments, although
5580 the @command{ftnchek} tool from @uref{ftp://ftp.netlib.org/fortran}
5581 or @uref{ftp://ftp.dsm.fordham.edu} is
5582 probably better for this purpose.}
5583 If the Fortran code containing any
5584 routines to be called from C is in file @file{joe.f}, use the command
5585 @kbd{f2c -P joe.f} to generate the file @file{joe.P} containing
5586 prototype information.
5587 @code{#include} this in the C which has to call
5588 the Fortran routines to make sure you get it right.
5590 @xref{Arrays,,Arrays (DIMENSION)}, for information on the differences
5591 between the way Fortran (including compilers like @command{g77}) and
5594 @node C++ Considerations
5595 @subsection C++ Considerations
5598 @command{f2c} can be used to generate suitable code for compilation with a
5599 C++ system using the @option{-C++} option.
5600 The important thing about linking @command{g77}-compiled
5601 code with C++ is that the prototypes for the @command{g77}
5602 routines must specify C linkage to avoid name mangling.
5603 So, use an @samp{extern "C"} declaration.
5604 @command{f2c}'s @option{-C++} option will not take care
5605 of this when generating skeletons or prototype files as above, however,
5606 it will avoid clashes with C++ reserved words in addition to those in C@.
5609 @subsection Startup Code
5611 @cindex startup code
5612 @cindex run-time, initialization
5613 @cindex initialization, run-time
5614 Unlike with some runtime systems,
5615 it shouldn't be necessary
5616 (unless there are bugs)
5617 to use a Fortran main program unit to ensure the
5618 runtime---specifically the I/O system---is initialized.
5620 However, to use the @command{g77} intrinsics @code{GETARG} and @code{IARGC},
5621 either the @code{main} routine from the @file{libg2c} library must be used,
5622 or the @code{f_setarg} routine
5623 (new as of @code{egcs} version 1.1 and @command{g77} version 0.5.23)
5624 must be called with the appropriate @code{argc} and @code{argv} arguments
5625 prior to the program calling @code{GETARG} or @code{IARGC}.
5627 To provide more flexibility for mixed-language programming
5628 involving @command{g77} while allowing for shared libraries,
5629 as of @code{egcs} version 1.1 and @command{g77} version 0.5.23,
5630 @command{g77}'s @code{main} routine in @code{libg2c}
5631 does the following, in order:
5635 Calls @code{f_setarg}
5636 with the incoming @code{argc} and @code{argv} arguments,
5637 in the same order as for @code{main} itself.
5639 This sets up the command-line environment
5640 for @code{GETARG} and @code{IARGC}.
5643 Calls @code{f_setsig} (with no arguments).
5645 This sets up the signaling and exception environment.
5648 Calls @code{f_init} (with no arguments).
5650 This initializes the I/O environment,
5651 though that should not be necessary,
5652 as all I/O functions in @code{libf2c}
5653 are believed to call @code{f_init} automatically,
5656 (A future version of @command{g77} might skip this explicit step,
5657 to speed up normal exit of a program.)
5660 Arranges for @code{f_exit} to be called (with no arguments)
5661 when the program exits.
5663 This ensures that the I/O environment is properly shut down
5664 before the program exits normally.
5665 Otherwise, output buffers might not be fully flushed,
5666 scratch files might not be deleted, and so on.
5668 The simple way @code{main} does this is
5669 to call @code{f_exit} itself after calling
5670 @code{MAIN__} (in the next step).
5672 However, this does not catch the cases where the program
5673 might call @code{exit} directly,
5674 instead of using the @code{EXIT} intrinsic
5675 (implemented as @code{exit_} in @code{libf2c}).
5677 So, @code{main} attempts to use
5678 the operating environment's @code{onexit} or @code{atexit}
5679 facility, if available,
5680 to cause @code{f_exit} to be called automatically
5681 upon any invocation of @code{exit}.
5684 Calls @code{MAIN__} (with no arguments).
5686 This starts executing the Fortran main program unit for
5688 (Both @command{g77} and @command{f2c} currently compile a main
5689 program unit so that its global name is @code{MAIN__}.)
5692 If no @code{onexit} or @code{atexit} is provided by the system,
5693 calls @code{f_exit}.
5696 Calls @code{exit} with a zero argument,
5697 to signal a successful program termination.
5700 Returns a zero value to the caller,
5701 to signal a successful program termination,
5702 in case @code{exit} doesn't exit on the system.
5705 All of the above names are C @code{extern} names,
5708 When using the @code{main} procedure provided by @command{g77}
5709 without a Fortran main program unit,
5710 you need to provide @code{MAIN__}
5711 as the entry point for your C code.
5712 (Make sure you link the object file that defines that
5713 entry point with the rest of your program.)
5715 To provide your own @code{main} procedure
5716 in place of @command{g77}'s,
5717 make sure you specify the object file defining that procedure
5718 @emph{before} @option{-lg2c} on the @command{g77} command line.
5719 Since the @option{-lg2c} option is implicitly provided,
5720 this is usually straightforward.
5721 (Use the @option{--verbose} option to see how and where
5722 @command{g77} implicitly adds @option{-lg2c} in a command line
5723 that will link the program.
5724 Feel free to specify @option{-lg2c} explicitly,
5727 However, when providing your own @code{main},
5728 make sure you perform the appropriate tasks in the
5730 For example, if your @code{main} does not call @code{f_setarg},
5731 make sure the rest of your application does not call
5732 @code{GETARG} or @code{IARGC}.
5734 And, if your @code{main} fails to ensure that @code{f_exit}
5735 is called upon program exit,
5736 some files might end up incompletely written,
5737 some scratch files might be left lying around,
5738 and some existing files being written might be left
5739 with old data not properly truncated at the end.
5741 Note that, generally, the @command{g77} operating environment
5742 does not depend on a procedure named @code{MAIN__} actually
5743 being called prior to any other @command{g77}-compiled code.
5744 That is, @code{MAIN__} does not, itself,
5745 set up any important operating-environment characteristics
5746 upon which other code might depend.
5747 This might change in future versions of @command{g77},
5748 with appropriate notification in the release notes.
5750 For more information, consult the source code for the above routines.
5751 These are in @file{@value{path-libf2c}/libF77/}, named @file{main.c},
5752 @file{setarg.c}, @file{setsig.c}, @file{getarg_.c}, and @file{iargc_.c}.
5754 Also, the file @file{@value{path-g77}/com.c} contains the code @command{g77}
5755 uses to open-code (inline) references to @code{IARGC}.
5757 @node Debugging and Interfacing
5758 @chapter Debugging and Interfacing
5761 @cindex calling C routines
5762 @cindex C routines calling Fortran
5763 @cindex f2c compatibility
5765 GNU Fortran currently generates code that is object-compatible with
5766 the @command{f2c} converter.
5767 Also, it avoids limitations in the current GBE, such as the
5768 inability to generate a procedure with
5769 multiple entry points, by generating code that is structured
5770 differently (in terms of procedure names, scopes, arguments, and
5771 so on) than might be expected.
5773 As a result, writing code in other languages that calls on, is
5774 called by, or shares in-memory data with @command{g77}-compiled code generally
5775 requires some understanding of the way @command{g77} compiles code for
5778 Similarly, using a debugger to debug @command{g77}-compiled
5779 code, even if that debugger supports native Fortran debugging, generally
5780 requires this sort of information.
5782 This section describes some of the basic information on how
5783 @command{g77} compiles code for constructs involving interfaces to other
5784 languages and to debuggers.
5786 @emph{Caution:} Much or all of this information pertains to only the current
5787 release of @command{g77}, sometimes even to using certain compiler options
5788 with @command{g77} (such as @option{-fno-f2c}).
5789 Do not write code that depends on this
5790 information without clearly marking said code as nonportable and
5791 subject to review for every new release of @command{g77}.
5793 is provided primarily to make debugging of code generated by this
5794 particular release of @command{g77} easier for the user, and partly to make
5795 writing (generally nonportable) interface code easier.
5797 activities require tracking changes in new version of @command{g77} as they
5798 are installed, because new versions can change the behaviors
5799 described in this section.
5802 * Main Program Unit:: How @command{g77} compiles a main program unit.
5803 * Procedures:: How @command{g77} constructs parameter lists
5805 * Functions:: Functions returning floating-point or character data.
5806 * Names:: Naming of user-defined variables, procedures, etc.
5807 * Common Blocks:: Accessing common variables while debugging.
5808 * Local Equivalence Areas:: Accessing @code{EQUIVALENCE} while debugging.
5809 * Complex Variables:: How @command{g77} performs complex arithmetic.
5810 * Arrays:: Dealing with (possibly multi-dimensional) arrays.
5811 * Adjustable Arrays:: Special consideration for adjustable arrays.
5812 * Alternate Entry Points:: How @command{g77} implements alternate @code{ENTRY}.
5813 * Alternate Returns:: How @command{g77} handles alternate returns.
5814 * Assigned Statement Labels:: How @command{g77} handles @code{ASSIGN}.
5815 * Run-time Library Errors:: Meanings of some @code{IOSTAT=} values.
5818 @node Main Program Unit
5819 @section Main Program Unit (PROGRAM)
5820 @cindex PROGRAM statement
5821 @cindex statements, PROGRAM
5823 When @command{g77} compiles a main program unit, it gives it the public
5824 procedure name @code{MAIN__}.
5825 The @code{libg2c} library has the actual @code{main()} procedure
5826 as is typical of C-based environments, and
5827 it is this procedure that performs some initial start-up
5828 activity and then calls @code{MAIN__}.
5830 Generally, @command{g77} and @code{libg2c} are designed so that you need not
5831 include a main program unit written in Fortran in your program---it
5832 can be written in C or some other language.
5833 Especially for I/O handling, this is the case, although @command{g77} version 0.5.16
5834 includes a bug fix for @code{libg2c} that solved a problem with using the
5835 @code{OPEN} statement as the first Fortran I/O activity in a program
5836 without a Fortran main program unit.
5838 However, if you don't intend to use @command{g77} (or @command{f2c}) to compile
5839 your main program unit---that is, if you intend to compile a @code{main()}
5840 procedure using some other language---you should carefully
5841 examine the code for @code{main()} in @code{libg2c}, found in the source
5842 file @file{@value{path-libf2c}/libF77/main.c}, to see what kinds of things
5843 might need to be done by your @code{main()} in order to provide the
5844 Fortran environment your Fortran code is expecting.
5846 @cindex @code{IArgC} intrinsic
5847 @cindex intrinsics, @code{IArgC}
5848 @cindex @code{GetArg} intrinsic
5849 @cindex intrinsics, @code{GetArg}
5850 For example, @code{libg2c}'s @code{main()} sets up the information used by
5851 the @code{IARGC} and @code{GETARG} intrinsics.
5852 Bypassing @code{libg2c}'s @code{main()}
5853 without providing a substitute for this activity would mean
5854 that invoking @code{IARGC} and @code{GETARG} would produce undefined
5858 @cindex main program unit, debugging
5862 When debugging, one implication of the fact that @code{main()}, which
5863 is the place where the debugged program ``starts'' from the
5864 debugger's point of view, is in @code{libg2c} is that you won't be
5865 starting your Fortran program at a point you recognize as your
5868 The standard way to get around this problem is to set a break
5869 point (a one-time, or temporary, break point will do) at
5870 the entrance to @code{MAIN__}, and then run the program.
5871 A convenient way to do so is to add the @command{gdb} command
5878 to the file @file{.gdbinit} in the directory in which you're debugging
5879 (using @command{gdb}).
5881 After doing this, the debugger will see the current execution
5882 point of the program as at the beginning of the main program
5883 unit of your program.
5885 Of course, if you really want to set a break point at some
5886 other place in your program and just start the program
5887 running, without first breaking at @code{MAIN__},
5888 that should work fine.
5891 @section Procedures (SUBROUTINE and FUNCTION)
5893 @cindex SUBROUTINE statement
5894 @cindex statements, SUBROUTINE
5895 @cindex FUNCTION statement
5896 @cindex statements, FUNCTION
5897 @cindex signature of procedures
5899 Currently, @command{g77} passes arguments via reference---specifically,
5900 by passing a pointer to the location in memory of a variable, array,
5901 array element, a temporary location that holds the result of evaluating an
5902 expression, or a temporary or permanent location that holds the value
5905 Procedures that accept @code{CHARACTER} arguments are implemented by
5906 @command{g77} so that each @code{CHARACTER} argument has two actual arguments.
5908 The first argument occupies the expected position in the
5909 argument list and has the user-specified name.
5911 is a pointer to an array of characters, passed by the caller.
5913 The second argument is appended to the end of the user-specified
5914 calling sequence and is named @samp{__g77_length_@var{x}}, where @var{x}
5915 is the user-specified name.
5916 This argument is of the C type @code{ftnlen}
5917 (see @file{@value{path-libf2c}/g2c.h.in} for information on that type) and
5918 is the number of characters the caller has allocated in the
5919 array pointed to by the first argument.
5921 A procedure will ignore the length argument if @samp{X} is not declared
5922 @code{CHARACTER*(*)}, because for other declarations, it knows the
5924 Not all callers necessarily ``know'' this, however, which
5925 is why they all pass the extra argument.
5927 The contents of the @code{CHARACTER} argument are specified by the
5928 address passed in the first argument (named after it).
5929 The procedure can read or write these contents as appropriate.
5931 When more than one @code{CHARACTER} argument is present in the argument
5932 list, the length arguments are appended in the order
5933 the original arguments appear.
5934 So @samp{CALL FOO('HI','THERE')} is implemented in
5935 C as @samp{foo("hi","there",2,5);}, ignoring the fact that @command{g77}
5936 does not provide the trailing null bytes on the constant
5937 strings (@command{f2c} does provide them, but they are unnecessary in
5938 a Fortran environment, and you should not expect them to be
5941 Note that the above information applies to @code{CHARACTER} variables and
5942 arrays @strong{only}.
5943 It does @strong{not} apply to external @code{CHARACTER}
5944 functions or to intrinsic @code{CHARACTER} functions.
5945 That is, no second length argument is passed to @samp{FOO} in this case:
5954 Nor does @samp{FOO} expect such an argument in this case:
5962 Because of this implementation detail, if a program has a bug
5963 such that there is disagreement as to whether an argument is
5964 a procedure, and the type of the argument is @code{CHARACTER}, subtle
5965 symptoms might appear.
5968 @section Functions (FUNCTION and RETURN)
5970 @cindex FUNCTION statement
5971 @cindex statements, FUNCTION
5972 @cindex RETURN statement
5973 @cindex statements, RETURN
5974 @cindex return type of functions
5976 @command{g77} handles in a special way functions that return the following
5988 For @code{CHARACTER}, @command{g77} implements a subroutine (a C function
5989 returning @code{void})
5990 with two arguments prepended: @samp{__g77_result}, which the caller passes
5991 as a pointer to a @code{char} array expected to hold the return value,
5992 and @samp{__g77_length}, which the caller passes as an @code{ftnlen} value
5993 specifying the length of the return value as declared in the calling
5995 For @code{CHARACTER*(*)}, the called function uses @samp{__g77_length}
5996 to determine the size of the array that @samp{__g77_result} points to;
5997 otherwise, it ignores that argument.
5999 For @code{COMPLEX}, when @option{-ff2c} is in
6000 force, @command{g77} implements
6001 a subroutine with one argument prepended: @samp{__g77_result}, which the
6002 caller passes as a pointer to a variable of the type of the function.
6003 The called function writes the return value into this variable instead
6004 of returning it as a function value.
6005 When @option{-fno-f2c} is in force,
6006 @command{g77} implements a @code{COMPLEX} function as @command{gcc}'s
6007 @samp{__complex__ float} or @samp{__complex__ double} function
6008 (or an emulation thereof, when @option{-femulate-complex} is in effect),
6009 returning the result of the function in the same way as @command{gcc} would.
6011 For @code{REAL(KIND=1)}, when @option{-ff2c} is in force, @command{g77} implements
6012 a function that actually returns @code{REAL(KIND=2)} (typically
6013 C's @code{double} type).
6014 When @option{-fno-f2c} is in force, @code{REAL(KIND=1)}
6015 functions return @code{float}.
6019 @cindex symbol names
6020 @cindex transforming symbol names
6022 Fortran permits each implementation to decide how to represent
6023 names as far as how they're seen in other contexts, such as debuggers
6024 and when interfacing to other languages, and especially as far
6025 as how casing is handled.
6027 External names---names of entities that are public, or ``accessible'',
6028 to all modules in a program---normally have an underscore (@samp{_})
6029 appended by @command{g77},
6030 to generate code that is compatible with @command{f2c}.
6031 External names include names of Fortran things like common blocks,
6032 external procedures (subroutines and functions, but not including
6033 statement functions, which are internal procedures), and entry point
6036 However, use of the @option{-fno-underscoring} option
6037 disables this kind of transformation of external names (though inhibiting
6038 the transformation certainly improves the chances of colliding with
6039 incompatible externals written in other languages---but that
6040 might be intentional.
6042 @cindex -fno-underscoring option
6043 @cindex options, -fno-underscoring
6044 @cindex -fno-second-underscore option
6045 @cindex options, -fno-underscoring
6046 When @option{-funderscoring} is in force, any name (external or local)
6047 that already has at least one underscore in it is
6048 implemented by @command{g77} by appending two underscores.
6049 (This second underscore can be disabled via the
6050 @option{-fno-second-underscore} option.)
6051 External names are changed this way for @command{f2c} compatibility.
6052 Local names are changed this way to avoid collisions with external names
6053 that are different in the source code---@command{f2c} does the same thing, but
6054 there's no compatibility issue there except for user expectations while
6065 Here, a user would, in the debugger, refer to this variable using the
6066 name @samp{max_cost__} (or @samp{MAX_COST__} or @samp{Max_Cost__},
6067 as described below).
6068 (We hope to improve @command{g77} in this regard in the future---don't
6069 write scripts depending on this behavior!
6070 Also, consider experimenting with the @option{-fno-underscoring}
6071 option to try out debugging without having to massage names by
6074 @command{g77} provides a number of command-line options that allow the user
6075 to control how case mapping is handled for source files.
6076 The default is the traditional UNIX model for Fortran compilers---names
6077 are mapped to lower case.
6078 Other command-line options can be specified to map names to upper
6079 case, or to leave them exactly as written in the source file.
6088 Here, it is normally the case that the variable assigned will be named
6090 This would be the name to enter when using a debugger to
6091 access the variable.
6093 However, depending on the command-line options specified, the
6094 name implemented by @command{g77} might instead be @samp{FOO} or even
6095 @samp{Foo}, thus affecting how debugging is done.
6104 This would normally call a procedure that, if it were in a separate C program,
6105 be defined starting with the line:
6112 However, @command{g77} command-line options could be used to change the casing
6113 of names, resulting in the name @samp{FOO_} or @samp{Foo_} being given to the
6114 procedure instead of @samp{foo_}, and the @option{-fno-underscoring} option
6115 could be used to inhibit the appending of the underscore to the name.
6118 @section Common Blocks (COMMON)
6119 @cindex common blocks
6120 @cindex @code{COMMON} statement
6121 @cindex statements, @code{COMMON}
6123 @command{g77} names and lays out @code{COMMON} areas
6124 the same way @command{f2c} does,
6125 for compatibility with @command{f2c}.
6127 @node Local Equivalence Areas
6128 @section Local Equivalence Areas (EQUIVALENCE)
6129 @cindex equivalence areas
6130 @cindex local equivalence areas
6131 @cindex EQUIVALENCE statement
6132 @cindex statements, EQUIVALENCE
6134 @command{g77} treats storage-associated areas involving a @code{COMMON}
6135 block as explained in the section on common blocks.
6137 A local @code{EQUIVALENCE} area is a collection of variables and arrays
6138 connected to each other in any way via @code{EQUIVALENCE}, none of which are
6139 listed in a @code{COMMON} statement.
6141 (@emph{Note:} @command{g77} version 0.5.18 and earlier chose the name
6142 for @var{x} using a different method when more than one name was
6143 in the list of names of entities placed at the beginning of the
6145 Though the documentation specified that the first name listed in
6146 the @code{EQUIVALENCE} statements was chosen for @var{x}, @command{g77}
6147 in fact chose the name using a method that was so complicated,
6148 it seemed easier to change it to an alphabetical sort than to describe the
6149 previous method in the documentation.)
6151 @node Complex Variables
6152 @section Complex Variables (COMPLEX)
6153 @cindex complex variables
6154 @cindex imaginary part
6155 @cindex COMPLEX statement
6156 @cindex statements, COMPLEX
6158 As of 0.5.20, @command{g77} defaults to handling @code{COMPLEX} types
6159 (and related intrinsics, constants, functions, and so on)
6161 makes direct debugging involving these types in Fortran
6162 language mode difficult.
6164 Essentially, @command{g77} implements these types using an
6165 internal construct similar to C's @code{struct}, at least
6166 as seen by the @command{gcc} back end.
6168 Currently, the back end, when outputting debugging info with
6169 the compiled code for the assembler to digest, does not detect
6170 these @code{struct} types as being substitutes for Fortran
6172 As a result, the Fortran language modes of debuggers such as
6173 @command{gdb} see these types as C @code{struct} types, which
6174 they might or might not support.
6176 Until this is fixed, switch to C language mode to work with
6177 entities of @code{COMPLEX} type and then switch back to Fortran language
6179 (In @command{gdb}, this is accomplished via @samp{set lang c} and
6180 either @samp{set lang fortran} or @samp{set lang auto}.)
6183 @section Arrays (DIMENSION)
6184 @cindex DIMENSION statement
6185 @cindex statements, DIMENSION
6186 @cindex array ordering
6187 @cindex ordering, array
6188 @cindex column-major ordering
6189 @cindex row-major ordering
6192 Fortran uses ``column-major ordering'' in its arrays.
6193 This differs from other languages, such as C, which use ``row-major ordering''.
6194 The difference is that, with Fortran, array elements adjacent to
6195 each other in memory differ in the @emph{first} subscript instead of
6196 the last; @samp{A(5,10,20)} immediately follows @samp{A(4,10,20)},
6197 whereas with row-major ordering it would follow @samp{A(5,10,19)}.
6200 affects not only interfacing with and debugging Fortran code,
6201 it can greatly affect how code is designed and written, especially
6202 when code speed and size is a concern.
6204 Fortran also differs from C, a popular language for interfacing and
6205 to support directly in debuggers, in the way arrays are treated.
6206 In C, arrays are single-dimensional and have interesting relationships
6207 to pointers, neither of which is true for Fortran.
6208 As a result, dealing with Fortran arrays from within
6209 an environment limited to C concepts can be challenging.
6211 For example, accessing the array element @samp{A(5,10,20)} is easy enough
6212 in Fortran (use @samp{A(5,10,20)}), but in C some difficult machinations
6214 First, C would treat the A array as a single-dimension array.
6215 Second, C does not understand low bounds for arrays as does Fortran.
6216 Third, C assumes a low bound of zero (0), while Fortran defaults to a
6217 low bound of one (1) and can supports an arbitrary low bound.
6218 Therefore, calculations must be done
6219 to determine what the C equivalent of @samp{A(5,10,20)} would be, and these
6220 calculations require knowing the dimensions of @samp{A}.
6222 For @samp{DIMENSION A(2:11,21,0:29)}, the calculation of the offset of
6223 @samp{A(5,10,20)} would be:
6228 + (20-0)*(11-2+1)*(21-1+1)
6233 So the C equivalent in this case would be @samp{a[4293]}.
6235 When using a debugger directly on Fortran code, the C equivalent
6236 might not work, because some debuggers cannot understand the notion
6237 of low bounds other than zero. However, unlike @command{f2c}, @command{g77}
6238 does inform the GBE that a multi-dimensional array (like @samp{A}
6239 in the above example) is really multi-dimensional, rather than a
6240 single-dimensional array, so at least the dimensionality of the array
6243 Debuggers that understand Fortran should have no trouble with
6244 nonzero low bounds, but for non-Fortran debuggers, especially
6245 C debuggers, the above example might have a C equivalent of
6247 This calculation is arrived at by eliminating the subtraction
6248 of the lower bound in the first parenthesized expression on each
6249 line---that is, for @samp{(5-2)} substitute @samp{(5)}, for @samp{(10-1)}
6250 substitute @samp{(10)}, and for @samp{(20-0)} substitute @samp{(20)}.
6251 Actually, the implication of
6252 this can be that the expression @samp{*(&a[2][1][0] + 4293)} works fine,
6253 but that @samp{a[20][10][5]} produces the equivalent of
6254 @samp{*(&a[0][0][0] + 4305)} because of the missing lower bounds.
6256 Come to think of it, perhaps
6257 the behavior is due to the debugger internally compensating for
6258 the lower bounds by offsetting the base address of @samp{a}, leaving
6259 @samp{&a} set lower, in this case, than @samp{&a[2][1][0]} (the address of
6260 its first element as identified by subscripts equal to the
6261 corresponding lower bounds).
6263 You know, maybe nobody really needs to use arrays.
6265 @node Adjustable Arrays
6266 @section Adjustable Arrays (DIMENSION)
6267 @cindex arrays, adjustable
6268 @cindex adjustable arrays
6269 @cindex arrays, automatic
6270 @cindex automatic arrays
6271 @cindex DIMENSION statement
6272 @cindex statements, DIMENSION
6273 @cindex dimensioning arrays
6274 @cindex arrays, dimensioning
6276 Adjustable and automatic arrays in Fortran require the implementation
6278 case, the @command{g77} compiler) to ``memorize'' the expressions that
6279 dimension the arrays each time the procedure is invoked.
6280 This is so that subsequent changes to variables used in those
6281 expressions, made during execution of the procedure, do not
6282 have any effect on the dimensions of those arrays.
6299 Here, the implementation should, when running the program, print something
6307 Note that this shows that while the value of @samp{N} was successfully
6308 changed, the size of the @samp{A} array remained at 5 elements.
6310 To support this, @command{g77} generates code that executes before any user
6311 code (and before the internally generated computed @code{GOTO} to handle
6312 alternate entry points, as described below) that evaluates each
6313 (nonconstant) expression in the list of subscripts for an
6314 array, and saves the result of each such evaluation to be used when
6315 determining the size of the array (instead of re-evaluating the
6318 So, in the above example, when @samp{X} is first invoked, code is
6319 executed that copies the value of @samp{N} to a temporary.
6320 And that same temporary serves as the actual high bound for the single
6321 dimension of the @samp{A} array (the low bound being the constant 1).
6322 Since the user program cannot (legitimately) change the value
6323 of the temporary during execution of the procedure, the size
6324 of the array remains constant during each invocation.
6326 For alternate entry points, the code @command{g77} generates takes into
6327 account the possibility that a dummy adjustable array is not actually
6328 passed to the actual entry point being invoked at that time.
6329 In that case, the public procedure implementing the entry point
6330 passes to the master private procedure implementing all the
6331 code for the entry points a @code{NULL} pointer where a pointer to that
6332 adjustable array would be expected.
6333 The @command{g77}-generated code
6334 doesn't attempt to evaluate any of the expressions in the subscripts
6335 for an array if the pointer to that array is @code{NULL} at run time in
6337 (Don't depend on this particular implementation
6338 by writing code that purposely passes @code{NULL} pointers where the
6339 callee expects adjustable arrays, even if you know the callee
6340 won't reference the arrays---nor should you pass @code{NULL} pointers
6341 for any dummy arguments used in calculating the bounds of such
6342 arrays or leave undefined any values used for that purpose in
6343 COMMON---because the way @command{g77} implements these things might
6344 change in the future!)
6346 @node Alternate Entry Points
6347 @section Alternate Entry Points (ENTRY)
6348 @cindex alternate entry points
6349 @cindex entry points
6350 @cindex ENTRY statement
6351 @cindex statements, ENTRY
6353 The GBE does not understand the general concept of
6354 alternate entry points as Fortran provides via the ENTRY statement.
6355 @command{g77} gets around this by using an approach to compiling procedures
6356 having at least one @code{ENTRY} statement that is almost identical to the
6357 approach used by @command{f2c}.
6358 (An alternate approach could be used that
6359 would probably generate faster, but larger, code that would also
6360 be a bit easier to debug.)
6362 Information on how @command{g77} implements @code{ENTRY} is provided for those
6363 trying to debug such code.
6364 The choice of implementation seems
6365 unlikely to affect code (compiled in other languages) that interfaces
6368 @command{g77} compiles exactly one public procedure for the primary entry
6369 point of a procedure plus each @code{ENTRY} point it specifies, as usual.
6370 That is, in terms of the public interface, there is no difference
6389 The difference between the above two cases lies in the code compiled
6390 for the @samp{X} and @samp{Y} procedures themselves, plus the fact that,
6391 for the second case, an extra internal procedure is compiled.
6393 For every Fortran procedure with at least one @code{ENTRY}
6394 statement, @command{g77} compiles an extra procedure
6395 named @samp{__g77_masterfun_@var{x}}, where @var{x} is
6396 the name of the primary entry point (which, in the above case,
6397 using the standard compiler options, would be @samp{x_} in C).
6399 This extra procedure is compiled as a private procedure---that is,
6400 a procedure not accessible by name to separately compiled modules.
6401 It contains all the code in the program unit, including the code
6402 for the primary entry point plus for every entry point.
6403 (The code for each public procedure is quite short, and explained later.)
6405 The extra procedure has some other interesting characteristics.
6407 The argument list for this procedure is invented by @command{g77}.
6409 a single integer argument named @samp{__g77_which_entrypoint},
6410 passed by value (as in Fortran's @samp{%VAL()} intrinsic), specifying the
6411 entry point index---0 for the primary entry point, 1 for the
6412 first entry point (the first @code{ENTRY} statement encountered), 2 for
6413 the second entry point, and so on.
6415 It also contains, for functions returning @code{CHARACTER} and
6416 (when @option{-ff2c} is in effect) @code{COMPLEX} functions,
6417 and for functions returning different types among the
6418 @code{ENTRY} statements (e.g. @samp{REAL FUNCTION R()}
6419 containing @samp{ENTRY I()}), an argument named @samp{__g77_result} that
6420 is expected at run time to contain a pointer to where to store
6421 the result of the entry point.
6422 For @code{CHARACTER} functions, this
6423 storage area is an array of the appropriate number of characters;
6424 for @code{COMPLEX} functions, it is the appropriate area for the return
6425 type; for multiple-return-type functions, it is a union of all the supported return
6426 types (which cannot include @code{CHARACTER}, since combining @code{CHARACTER}
6427 and non-@code{CHARACTER} return types via @code{ENTRY} in a single function
6428 is not supported by @command{g77}).
6430 For @code{CHARACTER} functions, the @samp{__g77_result} argument is followed
6431 by yet another argument named @samp{__g77_length} that, at run time,
6432 specifies the caller's expected length of the returned value.
6433 Note that only @code{CHARACTER*(*)} functions and entry points actually
6434 make use of this argument, even though it is always passed by
6435 all callers of public @code{CHARACTER} functions (since the caller does not
6436 generally know whether such a function is @code{CHARACTER*(*)} or whether
6437 there are any other callers that don't have that information).
6439 The rest of the argument list is the union of all the arguments
6440 specified for all the entry points (in their usual forms, e.g.
6441 @code{CHARACTER} arguments have extra length arguments, all appended at
6442 the end of this list).
6443 This is considered the ``master list'' of
6446 The code for this procedure has, before the code for the first
6447 executable statement, code much like that for the following Fortran
6451 GOTO (100000,100001,100002), __g77_which_entrypoint
6452 100000 @dots{}code for primary entry point@dots{}
6453 100001 @dots{}code immediately following first ENTRY statement@dots{}
6454 100002 @dots{}code immediately following second ENTRY statement@dots{}
6458 (Note that invalid Fortran statement labels and variable names
6459 are used in the above example to highlight the fact that it
6460 represents code generated by the @command{g77} internals, not code to be
6461 written by the user.)
6463 It is this code that, when the procedure is called, picks which
6464 entry point to start executing.
6466 Getting back to the public procedures (@samp{x} and @samp{Y} in the original
6467 example), those procedures are fairly simple.
6469 are just like they would be if they were self-contained procedures
6470 (without @code{ENTRY}), of course, since that is what the callers
6472 Their code consists of simply calling the private
6473 procedure, described above, with the appropriate extra arguments
6474 (the entry point index, and perhaps a pointer to a multiple-type-
6475 return variable, local to the public procedure, that contains
6476 all the supported returnable non-character types).
6478 that are not listed for a given entry point that are listed for
6479 other entry points, and therefore that are in the ``master list''
6480 for the private procedure, null pointers (in C, the @code{NULL} macro)
6482 Also, for entry points that are part of a multiple-type-
6483 returning function, code is compiled after the call of the private
6484 procedure to extract from the multi-type union the appropriate result,
6485 depending on the type of the entry point in question, returning
6486 that result to the original caller.
6488 When debugging a procedure containing alternate entry points, you
6489 can either set a break point on the public procedure itself (e.g.
6490 a break point on @samp{X} or @samp{Y}) or on the private procedure that
6491 contains most of the pertinent code (e.g. @samp{__g77_masterfun_@var{x}}).
6492 If you do the former, you should use the debugger's command to
6493 ``step into'' the called procedure to get to the actual code; with
6494 the latter approach, the break point leaves you right at the
6495 actual code, skipping over the public entry point and its call
6496 to the private procedure (unless you have set a break point there
6497 as well, of course).
6499 Further, the list of dummy arguments that is visible when the
6500 private procedure is active is going to be the expanded version
6501 of the list for whichever particular entry point is active,
6502 as explained above, and the way in which return values are
6503 handled might well be different from how they would be handled
6504 for an equivalent single-entry function.
6506 @node Alternate Returns
6507 @section Alternate Returns (SUBROUTINE and RETURN)
6509 @cindex alternate returns
6510 @cindex SUBROUTINE statement
6511 @cindex statements, SUBROUTINE
6512 @cindex RETURN statement
6513 @cindex statements, RETURN
6515 Subroutines with alternate returns (e.g. @samp{SUBROUTINE X(*)} and
6516 @samp{CALL X(*50)}) are implemented by @command{g77} as functions returning
6517 the C @code{int} type.
6518 The actual alternate-return arguments are omitted from the calling sequence.
6519 Instead, the caller uses
6520 the return value to do a rough equivalent of the Fortran
6521 computed-@code{GOTO} statement, as in @samp{GOTO (50), X()} in the
6522 example above (where @samp{X} is quietly declared as an @code{INTEGER(KIND=1)}
6523 function), and the callee just returns whatever integer
6524 is specified in the @code{RETURN} statement for the subroutine
6525 For example, @samp{RETURN 1} is implemented as @samp{X = 1} followed
6527 in C, and @samp{RETURN} by itself is @samp{X = 0} and @samp{RETURN}).
6529 @node Assigned Statement Labels
6530 @section Assigned Statement Labels (ASSIGN and GOTO)
6531 @cindex assigned statement labels
6532 @cindex statement labels, assigned
6533 @cindex ASSIGN statement
6534 @cindex statements, ASSIGN
6535 @cindex GOTO statement
6536 @cindex statements, GOTO
6538 For portability to machines where a pointer (such as to a label,
6539 which is how @command{g77} implements @code{ASSIGN} and its relatives,
6540 the assigned-@code{GOTO} and assigned-@code{FORMAT}-I/O statements)
6541 is wider (bitwise) than an @code{INTEGER(KIND=1)}, @command{g77}
6542 uses a different memory location to hold the @code{ASSIGN}ed value of a variable
6543 than it does the numerical value in that variable, unless the
6544 variable is wide enough (can hold enough bits).
6546 In particular, while @command{g77} implements
6553 as, in C notation, @samp{i = 10;}, it implements
6560 as, in GNU's extended C notation (for the label syntax),
6561 @samp{__g77_ASSIGN_I = &&L10;} (where @samp{L10} is just a massaging
6562 of the Fortran label @samp{10} to make the syntax C-like; @command{g77} doesn't
6563 actually generate the name @samp{L10} or any other name like that,
6564 since debuggers cannot access labels anyway).
6566 While this currently means that an @code{ASSIGN} statement does not
6567 overwrite the numeric contents of its target variable, @emph{do not}
6568 write any code depending on this feature.
6569 @command{g77} has already changed this implementation across
6570 versions and might do so in the future.
6571 This information is provided only to make debugging Fortran programs
6572 compiled with the current version of @command{g77} somewhat easier.
6573 If there's no debugger-visible variable named @samp{__g77_ASSIGN_I}
6574 in a program unit that does @samp{ASSIGN 10 TO I}, that probably
6575 means @command{g77} has decided it can store the pointer to the label directly
6576 into @samp{I} itself.
6578 @xref{Ugly Assigned Labels}, for information on a command-line option
6579 to force @command{g77} to use the same storage for both normal and
6580 assigned-label uses of a variable.
6582 @node Run-time Library Errors
6583 @section Run-time Library Errors
6585 @cindex error values
6586 @cindex error messages
6587 @cindex messages, run-time
6590 The @code{libg2c} library currently has the following table to relate
6591 error code numbers, returned in @code{IOSTAT=} variables, to messages.
6592 This information should, in future versions of this document, be
6593 expanded upon to include detailed descriptions of each message.
6595 In line with good coding practices, any of the numbers in the
6596 list below should @emph{not} be directly written into Fortran
6598 Instead, make a separate @code{INCLUDE} file that defines
6599 @code{PARAMETER} names for them, and use those in your code,
6600 so you can more easily change the actual numbers in the future.
6602 The information below is culled from the definition
6603 of @code{F_err} in @file{f/runtime/libI77/err.c} in the
6604 @command{g77} source tree.
6607 100: "error in format"
6608 101: "illegal unit number"
6609 102: "formatted io not allowed"
6610 103: "unformatted io not allowed"
6611 104: "direct io not allowed"
6612 105: "sequential io not allowed"
6613 106: "can't backspace file"
6614 107: "null file name"
6615 108: "can't stat file"
6616 109: "unit not connected"
6617 110: "off end of record"
6618 111: "truncation failed in endfile"
6619 112: "incomprehensible list input"
6620 113: "out of free space"
6621 114: "unit not connected"
6622 115: "read unexpected character"
6623 116: "bad logical input field"
6624 117: "bad variable type"
6625 118: "bad namelist name"
6626 119: "variable not in namelist"
6627 120: "no end record"
6628 121: "variable count incorrect"
6629 122: "subscript for scalar variable"
6630 123: "invalid array section"
6631 124: "substring out of bounds"
6632 125: "subscript out of bounds"
6633 126: "can't read file"
6634 127: "can't write file"
6635 128: "'new' file exists"
6636 129: "can't append to file"
6637 130: "non-positive record number"
6638 131: "I/O started while already doing I/O"
6641 @node Collected Fortran Wisdom
6642 @chapter Collected Fortran Wisdom
6645 @cindex code, legacy
6646 @cindex writing code
6647 @cindex code, writing
6649 Most users of @command{g77} can be divided into two camps:
6653 Those writing new Fortran code to be compiled by @command{g77}.
6656 Those using @command{g77} to compile existing, ``legacy'' code.
6659 Users writing new code generally understand most of the necessary
6660 aspects of Fortran to write ``mainstream'' code, but often need
6661 help deciding how to handle problems, such as the construction
6662 of libraries containing @code{BLOCK DATA}.
6664 Users dealing with ``legacy'' code sometimes don't have much
6665 experience with Fortran, but believe that the code they're compiling
6666 already works when compiled by other compilers (and might
6667 not understand why, as is sometimes the case, it doesn't work
6668 when compiled by @command{g77}).
6670 The following information is designed to help users do a better job
6671 coping with existing, ``legacy'' Fortran code, and with writing
6675 * Advantages Over f2c:: If @command{f2c} is so great, why @command{g77}?
6676 * Block Data and Libraries:: How @command{g77} solves a common problem.
6677 * Loops:: Fortran @code{DO} loops surprise many people.
6678 * Working Programs:: Getting programs to work should be done first.
6679 * Overly Convenient Options:: Temptations to avoid, habits to not form.
6680 * Faster Programs:: Everybody wants these, but at what cost?
6683 @node Advantages Over f2c
6684 @section Advantages Over f2c
6686 Without @command{f2c}, @command{g77} would have taken much longer to
6687 do and probably not been as good for quite a while.
6688 Sometimes people who notice how much @command{g77} depends on, and
6689 documents encouragement to use, @command{f2c} ask why @command{g77}
6690 was created if @command{f2c} already existed.
6692 This section gives some basic answers to these questions, though it
6693 is not intended to be comprehensive.
6696 * Language Extensions:: Features used by Fortran code.
6697 * Diagnostic Abilities:: Abilities to spot problems early.
6698 * Compiler Options:: Features helpful to accommodate legacy code, etc.
6699 * Compiler Speed:: Speed of the compilation process.
6700 * Program Speed:: Speed of the generated, optimized code.
6701 * Ease of Debugging:: Debugging ease-of-use at the source level.
6702 * Character and Hollerith Constants:: A byte saved is a byte earned.
6705 @node Language Extensions
6706 @subsection Language Extensions
6708 @command{g77} offers several extensions to FORTRAN 77 language that @command{f2c}
6716 @code{CYCLE} and @code{EXIT}
6725 @code{KIND=} and @code{LEN=} notation
6728 Semicolon as statement separator
6731 Constant expressions in @code{FORMAT} statements
6732 (such as @samp{FORMAT(I<J>)},
6733 where @samp{J} is a @code{PARAMETER} named constant)
6736 @code{MvBits} intrinsic
6739 @code{libU77} (Unix-compatibility) library,
6740 with routines known to compiler as intrinsics
6741 (so they work even when compiler options are used
6742 to change the interfaces used by Fortran routines)
6745 @command{g77} also implements iterative @code{DO} loops
6746 so that they work even in the presence of certain ``extreme'' inputs,
6747 unlike @command{f2c}.
6750 However, @command{f2c} offers a few that @command{g77} doesn't, such as:
6754 Intrinsics in @code{PARAMETER} statements
6757 Array bounds expressions (such as @samp{REAL M(N(2))})
6760 @code{AUTOMATIC} statement
6763 It is expected that @command{g77} will offer some or all of these missing
6764 features at some time in the future.
6766 @node Diagnostic Abilities
6767 @subsection Diagnostic Abilities
6769 @command{g77} offers better diagnosis of problems in @code{FORMAT} statements.
6770 @command{f2c} doesn't, for example, emit any diagnostic for
6771 @samp{FORMAT(XZFAJG10324)},
6772 leaving that to be diagnosed, at run time, by
6773 the @code{libf2c} run-time library.
6775 @node Compiler Options
6776 @subsection Compiler Options
6778 @command{g77} offers compiler options that @command{f2c} doesn't,
6779 most of which are designed to more easily accommodate
6784 Two that control the automatic appending of extra
6785 underscores to external names
6788 One that allows dollar signs (@samp{$}) in symbol names
6791 A variety that control acceptance of various
6795 Several that specify acceptable use of upper and lower case
6799 Many that enable, disable, delete, or hide
6800 groups of intrinsics
6803 One to specify the length of fixed-form source lines
6807 One to specify the the source code is written in
6808 Fortran-90-style free-form
6811 However, @command{f2c} offers a few that @command{g77} doesn't,
6812 like an option to have @code{REAL} default to @code{REAL*8}.
6813 It is expected that @command{g77} will offer all of the
6814 missing options pertinent to being a Fortran compiler
6815 at some time in the future.
6817 @node Compiler Speed
6818 @subsection Compiler Speed
6820 Saving the steps of writing and then rereading C code is a big reason
6821 why @command{g77} should be able to compile code much faster than using
6822 @command{f2c} in conjunction with the equivalent invocation of @command{gcc}.
6824 However, due to @command{g77}'s youth, lots of self-checking is still being
6826 As a result, this improvement is as yet unrealized
6827 (though the potential seems to be there for quite a big speedup
6829 It is possible that, as of version 0.5.18, @command{g77}
6830 is noticeably faster compiling many Fortran source files than using
6831 @command{f2c} in conjunction with @command{gcc}.
6834 @subsection Program Speed
6836 @command{g77} has the potential to better optimize code than @command{f2c},
6837 even when @command{gcc} is used to compile the output of @command{f2c},
6838 because @command{f2c} must necessarily
6839 translate Fortran into a somewhat lower-level language (C) that cannot
6840 preserve all the information that is potentially useful for optimization,
6841 while @command{g77} can gather, preserve, and transmit that information directly
6844 For example, @command{g77} implements @code{ASSIGN} and assigned
6845 @code{GOTO} using direct assignment of pointers to labels and direct
6846 jumps to labels, whereas @command{f2c} maps the assigned labels to
6847 integer values and then uses a C @code{switch} statement to encode
6848 the assigned @code{GOTO} statements.
6850 However, as is typical, theory and reality don't quite match, at least
6851 not in all cases, so it is still the case that @command{f2c} plus @command{gcc}
6852 can generate code that is faster than @command{g77}.
6854 Version 0.5.18 of @command{g77} offered default
6855 settings and options, via patches to the @command{gcc}
6856 back end, that allow for better program speed, though
6857 some of these improvements also affected the performance
6858 of programs translated by @command{f2c} and then compiled
6859 by @command{g77}'s version of @command{gcc}.
6861 Version 0.5.20 of @command{g77} offers further performance
6862 improvements, at least one of which (alias analysis) is
6863 not generally applicable to @command{f2c} (though @command{f2c}
6864 could presumably be changed to also take advantage of
6865 this new capability of the @command{gcc} back end, assuming
6866 this is made available in an upcoming release of @command{gcc}).
6868 @node Ease of Debugging
6869 @subsection Ease of Debugging
6871 Because @command{g77} compiles directly to assembler code like @command{gcc},
6872 instead of translating to an intermediate language (C) as does @command{f2c},
6873 support for debugging can be better for @command{g77} than @command{f2c}.
6875 However, although @command{g77} might be somewhat more ``native'' in terms of
6876 debugging support than @command{f2c} plus @command{gcc}, there still are a lot
6877 of things ``not quite right''.
6878 Many of the important ones should be resolved in the near future.
6880 For example, @command{g77} doesn't have to worry about reserved names
6881 like @command{f2c} does.
6882 Given @samp{FOR = WHILE}, @command{f2c} must necessarily
6883 translate this to something @emph{other} than
6884 @samp{for = while;}, because C reserves those words.
6886 However, @command{g77} does still uses things like an extra level of indirection
6887 for @code{ENTRY}-laden procedures---in this case, because the back end doesn't
6888 yet support multiple entry points.
6890 Another example is that, given
6898 the @command{g77} user should be able to access the variables directly, by name,
6899 without having to traverse C-like structures and unions, while @command{f2c}
6900 is unlikely to ever offer this ability (due to limitations in the
6903 Yet another example is arrays.
6904 @command{g77} represents them to the debugger
6905 using the same ``dimensionality'' as in the source code, while @command{f2c}
6906 must necessarily convert them all to one-dimensional arrays to fit
6907 into the confines of the C language.
6908 However, the level of support
6909 offered by debuggers for interactive Fortran-style access to arrays
6910 as compiled by @command{g77} can vary widely.
6911 In some cases, it can actually
6912 be an advantage that @command{f2c} converts everything to widely supported
6915 In fairness, @command{g77} could do many of the things @command{f2c} does
6916 to get things working at least as well as @command{f2c}---for now,
6917 the developers prefer making @command{g77} work the
6918 way they think it is supposed to, and finding help improving the
6919 other products (the back end of @command{gcc}; @command{gdb}; and so on)
6920 to get things working properly.
6922 @node Character and Hollerith Constants
6923 @subsection Character and Hollerith Constants
6924 @cindex character constants
6925 @cindex constants, character
6926 @cindex Hollerith constants
6927 @cindex constants, Hollerith
6928 @cindex trailing null byte
6929 @cindex null byte, trailing
6930 @cindex zero byte, trailing
6932 To avoid the extensive hassle that would be needed to avoid this,
6933 @command{f2c} uses C character constants to encode character and Hollerith
6935 That means a constant like @samp{'HELLO'} is translated to
6936 @samp{"hello"} in C, which further means that an extra null byte is
6937 present at the end of the constant.
6938 This null byte is superfluous.
6940 @command{g77} does not generate such null bytes.
6941 This represents significant
6942 savings of resources, such as on systems where @file{/dev/null} or
6943 @file{/dev/zero} represent bottlenecks in the systems' performance,
6944 because @command{g77} simply asks for fewer zeros from the operating
6945 system than @command{f2c}.
6946 (Avoiding spurious use of zero bytes, each byte typically have
6947 eight zero bits, also reduces the liabilities in case
6948 Microsoft's rumored patent on the digits 0 and 1 is upheld.)
6950 @node Block Data and Libraries
6951 @section Block Data and Libraries
6952 @cindex block data and libraries
6953 @cindex BLOCK DATA statement
6954 @cindex statements, BLOCK DATA
6955 @cindex libraries, containing BLOCK DATA
6956 @cindex f2c compatibility
6957 @cindex compatibility, f2c
6959 To ensure that block data program units are linked, especially a concern
6960 when they are put into libraries, give each one a name (as in
6961 @samp{BLOCK DATA FOO}) and make sure there is an @samp{EXTERNAL FOO}
6962 statement in every program unit that uses any common block
6963 initialized by the corresponding @code{BLOCK DATA}.
6964 @command{g77} currently compiles a @code{BLOCK DATA} as if it were a
6966 that is, it generates an actual procedure having the appropriate name.
6967 The procedure does nothing but return immediately if it happens to be
6969 For @samp{EXTERNAL FOO}, where @samp{FOO} is not otherwise referenced in the
6970 same program unit, @command{g77} assumes there exists a @samp{BLOCK DATA FOO}
6971 in the program and ensures that by generating a
6972 reference to it so the linker will make sure it is present.
6973 (Specifically, @command{g77} outputs in the data section a static pointer to the
6974 external name @samp{FOO}.)
6976 The implementation @command{g77} currently uses to make this work is
6977 one of the few things not compatible with @command{f2c} as currently
6979 @command{f2c} currently does nothing with @samp{EXTERNAL FOO} except
6980 issue a warning that @samp{FOO} is not otherwise referenced,
6981 and, for @samp{BLOCK DATA FOO},
6982 @command{f2c} doesn't generate a dummy procedure with the name @samp{FOO}.
6983 The upshot is that you shouldn't mix @command{f2c} and @command{g77} in
6984 this particular case.
6985 If you use @command{f2c} to compile @samp{BLOCK DATA FOO},
6986 then any @command{g77}-compiled program unit that says @samp{EXTERNAL FOO}
6987 will result in an unresolved reference when linked.
6989 opposite, then @samp{FOO} might not be linked in under various
6990 circumstances (such as when @samp{FOO} is in a library, or you're
6991 using a ``clever'' linker---so clever, it produces a broken program
6992 with little or no warning by omitting initializations of global data
6993 because they are contained in unreferenced procedures).
6995 The changes you make to your code to make @command{g77} handle this situation,
6996 however, appear to be a widely portable way to handle it.
6997 That is, many systems permit it (as they should, since the
6998 FORTRAN 77 standard permits @samp{EXTERNAL FOO} when @samp{FOO}
6999 is a block data program unit), and of the ones
7000 that might not link @samp{BLOCK DATA FOO} under some circumstances, most of
7001 them appear to do so once @samp{EXTERNAL FOO} is present in the appropriate
7004 Here is the recommended approach to modifying a program containing
7005 a program unit such as the following:
7009 COMMON /VARS/ X, Y, Z
7010 DATA X, Y, Z / 3., 4., 5. /
7015 If the above program unit might be placed in a library module, then
7016 ensure that every program unit in every program that references that
7017 particular @code{COMMON} area uses the @code{EXTERNAL} statement
7018 to force the area to be initialized.
7020 For example, change a program unit that starts with
7023 INTEGER FUNCTION CURX()
7024 COMMON /VARS/ X, Y, Z
7030 so that it uses the @code{EXTERNAL} statement, as in:
7033 INTEGER FUNCTION CURX()
7034 COMMON /VARS/ X, Y, Z
7041 That way, @samp{CURX} is compiled by @command{g77} (and many other
7042 compilers) so that the linker knows it must include @samp{FOO},
7043 the @code{BLOCK DATA} program unit that sets the initial values
7044 for the variables in @samp{VAR}, in the executable program.
7048 @cindex DO statement
7049 @cindex statements, DO
7050 @cindex trips, number of
7051 @cindex number of trips
7053 The meaning of a @code{DO} loop in Fortran is precisely specified
7054 in the Fortran standard@dots{}and is quite different from what
7055 many programmers might expect.
7057 In particular, Fortran iterative @code{DO} loops are implemented as if
7058 the number of trips through the loop is calculated @emph{before}
7059 the loop is entered.
7061 The number of trips for a loop is calculated from the @var{start},
7062 @var{end}, and @var{increment} values specified in a statement such as:
7065 DO @var{iter} = @var{start}, @var{end}, @var{increment}
7069 The trip count is evaluated using a fairly simple formula
7070 based on the three values following the @samp{=} in the
7071 statement, and it is that trip count that is effectively
7072 decremented during each iteration of the loop.
7073 If, at the beginning of an iteration of the loop, the
7074 trip count is zero or negative, the loop terminates.
7075 The per-loop-iteration modifications to @var{iter} are not
7076 related to determining whether to terminate the loop.
7078 There are two important things to remember about the trip
7083 It can be @emph{negative}, in which case it is
7084 treated as if it was zero---meaning the loop is
7085 not executed at all.
7088 The type used to @emph{calculate} the trip count
7089 is the same type as @var{iter}, but the final
7090 calculation, and thus the type of the trip
7091 count itself, always is @code{INTEGER(KIND=1)}.
7094 These two items mean that there are loops that cannot
7095 be written in straightforward fashion using the Fortran @code{DO}.
7097 For example, on a system with the canonical 32-bit two's-complement
7098 implementation of @code{INTEGER(KIND=1)}, the following loop will not work:
7101 DO I = -2000000000, 2000000000
7105 Although the @var{start} and @var{end} values are well within
7106 the range of @code{INTEGER(KIND=1)}, the @emph{trip count} is not.
7107 The expected trip count is 40000000001, which is outside
7108 the range of @code{INTEGER(KIND=1)} on many systems.
7110 Instead, the above loop should be constructed this way:
7115 IF (I .GT. 2000000000) EXIT
7122 The simple @code{DO} construct and the @code{EXIT} statement
7123 (used to leave the innermost loop)
7124 are F90 features that @command{g77} supports.
7126 Some Fortran compilers have buggy implementations of @code{DO},
7127 in that they don't follow the standard.
7128 They implement @code{DO} as a straightforward translation
7129 to what, in C, would be a @code{for} statement.
7130 Instead of creating a temporary variable to hold the trip count
7131 as calculated at run time, these compilers
7132 use the iteration variable @var{iter} to control
7133 whether the loop continues at each iteration.
7135 The bug in such an implementation shows up when the
7136 trip count is within the range of the type of @var{iter},
7137 but the magnitude of @samp{ABS(@var{end}) + ABS(@var{incr})}
7138 exceeds that range. For example:
7141 DO I = 2147483600, 2147483647
7145 A loop started by the above statement will work as implemented
7146 by @command{g77}, but the use, by some compilers, of a
7147 more C-like implementation akin to
7150 for (i = 2147483600; i <= 2147483647; ++i)
7154 produces a loop that does not terminate, because @samp{i}
7155 can never be greater than 2147483647, since incrementing it
7156 beyond that value overflows @samp{i}, setting it to -2147483648.
7157 This is a large, negative number that still is less than 2147483647.
7159 Another example of unexpected behavior of @code{DO} involves
7160 using a nonintegral iteration variable @var{iter}, that is,
7161 a @code{REAL} variable.
7162 Consider the following program:
7165 DATA BEGIN, END, STEP /.1, .31, .007/
7166 DO 10 R = BEGIN, END, STEP
7167 IF (R .GT. END) PRINT *, R, ' .GT. ', END, '!!'
7171 IF (R .LE. END) PRINT *, R, ' .LE. ', END, '!!'
7176 A C-like view of @code{DO} would hold that the two ``exclamatory''
7177 @code{PRINT} statements are never executed.
7178 However, this is the output of running the above program
7179 as compiled by @command{g77} on a GNU/Linux ix86 system:
7191 .310000002 .LE. .310000002!!
7194 Note that one of the two checks in the program turned up
7195 an apparent violation of the programmer's expectation---yet,
7196 the loop is correctly implemented by @command{g77}, in that
7197 it has 30 iterations.
7198 This trip count of 30 is correct when evaluated using
7199 the floating-point representations for the @var{begin},
7200 @var{end}, and @var{incr} values (.1, .31, .007) on GNU/Linux
7202 On other systems, an apparently more accurate trip count
7203 of 31 might result, but, nevertheless, @command{g77} is
7204 faithfully following the Fortran standard, and the result
7205 is not what the author of the sample program above
7206 apparently expected.
7207 (Such other systems might, for different values in the @code{DATA}
7208 statement, violate the other programmer's expectation,
7211 Due to this combination of imprecise representation
7212 of floating-point values and the often-misunderstood
7213 interpretation of @code{DO} by standard-conforming
7214 compilers such as @command{g77}, use of @code{DO} loops
7215 with @code{REAL} iteration
7216 variables is not recommended.
7217 Such use can be caught by specifying @option{-Wsurprising}.
7218 @xref{Warning Options}, for more information on this
7221 @node Working Programs
7222 @section Working Programs
7224 Getting Fortran programs to work in the first place can be
7225 quite a challenge---even when the programs already work on
7226 other systems, or when using other compilers.
7228 @command{g77} offers some facilities that might be useful for
7229 tracking down bugs in such programs.
7233 * Variables Assumed To Be Zero::
7234 * Variables Assumed To Be Saved::
7235 * Unwanted Variables::
7236 * Unused Arguments::
7237 * Surprising Interpretations of Code::
7238 * Aliasing Assumed To Work::
7239 * Output Assumed To Flush::
7240 * Large File Unit Numbers::
7241 * Floating-point precision::
7242 * Inconsistent Calling Sequences::
7246 @subsection Not My Type
7247 @cindex mistyped variables
7248 @cindex variables, mistyped
7249 @cindex mistyped functions
7250 @cindex functions, mistyped
7251 @cindex implicit typing
7253 A fruitful source of bugs in Fortran source code is use, or
7254 mis-use, of Fortran's implicit-typing feature, whereby the
7255 type of a variable, array, or function is determined by the
7256 first character of its name.
7258 Simple cases of this include statements like @samp{LOGX=9.227},
7259 without a statement such as @samp{REAL LOGX}.
7260 In this case, @samp{LOGX} is implicitly given @code{INTEGER(KIND=1)}
7261 type, with the result of the assignment being that it is given
7264 More involved cases include a function that is defined starting
7265 with a statement like @samp{DOUBLE PRECISION FUNCTION IPS(@dots{})}.
7266 Any caller of this function that does not also declare @samp{IPS}
7267 as type @code{DOUBLE PRECISION} (or, in GNU Fortran, @code{REAL(KIND=2)})
7268 is likely to assume it returns
7269 @code{INTEGER}, or some other type, leading to invalid results
7270 or even program crashes.
7272 The @option{-Wimplicit} option might catch failures to
7273 properly specify the types of
7274 variables, arrays, and functions in the code.
7276 However, in code that makes heavy use of Fortran's
7277 implicit-typing facility, this option might produce so
7278 many warnings about cases that are working, it would be
7279 hard to find the one or two that represent bugs.
7280 This is why so many experienced Fortran programmers strongly
7281 recommend widespread use of the @code{IMPLICIT NONE} statement,
7282 despite it not being standard FORTRAN 77, to completely turn
7283 off implicit typing.
7284 (@command{g77} supports @code{IMPLICIT NONE}, as do almost all
7285 FORTRAN 77 compilers.)
7287 Note that @option{-Wimplicit} catches only implicit typing of
7289 It does not catch implicit typing of expressions such
7291 Such expressions can be buggy as well---in fact, @samp{X**(2/3)}
7292 is equivalent to @samp{X**0}, due to the way Fortran expressions
7293 are given types and then evaluated.
7294 (In this particular case, the programmer probably wanted
7297 @node Variables Assumed To Be Zero
7298 @subsection Variables Assumed To Be Zero
7299 @cindex zero-initialized variables
7300 @cindex variables, assumed to be zero
7301 @cindex uninitialized variables
7303 Many Fortran programs were developed on systems that provided
7304 automatic initialization of all, or some, variables and arrays
7306 As a result, many of these programs depend, sometimes
7307 inadvertently, on this behavior, though to do so violates
7308 the Fortran standards.
7310 You can ask @command{g77} for this behavior by specifying the
7311 @option{-finit-local-zero} option when compiling Fortran code.
7312 (You might want to specify @option{-fno-automatic} as well,
7313 to avoid code-size inflation for non-optimized compilations.)
7315 Note that a program that works better when compiled with the
7316 @option{-finit-local-zero} option
7317 is almost certainly depending on a particular system's,
7318 or compiler's, tendency to initialize some variables to zero.
7319 It might be worthwhile finding such cases and fixing them,
7320 using techniques such as compiling with the @option{-O -Wuninitialized}
7321 options using @command{g77}.
7323 @node Variables Assumed To Be Saved
7324 @subsection Variables Assumed To Be Saved
7325 @cindex variables, retaining values across calls
7326 @cindex saved variables
7327 @cindex static variables
7329 Many Fortran programs were developed on systems that
7330 saved the values of all, or some, variables and arrays
7331 across procedure calls.
7332 As a result, many of these programs depend, sometimes
7333 inadvertently, on being able to assign a value to a
7334 variable, perform a @code{RETURN} to a calling procedure,
7335 and, upon subsequent invocation, reference the previously
7336 assigned variable to obtain the value.
7338 They expect this despite not using the @code{SAVE} statement
7339 to specify that the value in a variable is expected to survive
7340 procedure returns and calls.
7341 Depending on variables and arrays to retain values across
7342 procedure calls without using @code{SAVE} to require it violates
7343 the Fortran standards.
7345 You can ask @command{g77} to assume @code{SAVE} is specified for all
7346 relevant (local) variables and arrays by using the
7347 @option{-fno-automatic} option.
7349 Note that a program that works better when compiled with the
7350 @option{-fno-automatic} option
7351 is almost certainly depending on not having to use
7352 the @code{SAVE} statement as required by the Fortran standard.
7353 It might be worthwhile finding such cases and fixing them,
7354 using techniques such as compiling with the @samp{-O -Wuninitialized}
7355 options using @command{g77}.
7357 @node Unwanted Variables
7358 @subsection Unwanted Variables
7360 The @option{-Wunused} option can find bugs involving
7361 implicit typing, sometimes
7362 more easily than using @option{-Wimplicit} in code that makes
7363 heavy use of implicit typing.
7364 An unused variable or array might indicate that the
7365 spelling for its declaration is different from that of
7368 Other than cases involving typos, unused variables rarely
7369 indicate actual bugs in a program.
7370 However, investigating such cases thoroughly has, on occasion,
7371 led to the discovery of code that had not been completely
7372 written---where the programmer wrote declarations as needed
7373 for the whole algorithm, wrote some or even most of the code
7374 for that algorithm, then got distracted and forgot that the
7375 job was not complete.
7377 @node Unused Arguments
7378 @subsection Unused Arguments
7379 @cindex unused arguments
7380 @cindex arguments, unused
7382 As with unused variables, It is possible that unused arguments
7383 to a procedure might indicate a bug.
7384 Compile with @samp{-W -Wunused} option to catch cases of
7387 Note that @option{-W} also enables warnings regarding overflow
7388 of floating-point constants under certain circumstances.
7390 @node Surprising Interpretations of Code
7391 @subsection Surprising Interpretations of Code
7393 The @option{-Wsurprising} option can help find bugs involving
7394 expression evaluation or in
7395 the way @code{DO} loops with non-integral iteration variables
7397 Cases found by this option might indicate a difference of
7398 interpretation between the author of the code involved, and
7399 a standard-conforming compiler such as @command{g77}.
7400 Such a difference might produce actual bugs.
7402 In any case, changing the code to explicitly do what the
7403 programmer might have expected it to do, so @command{g77} and
7404 other compilers are more likely to follow the programmer's
7405 expectations, might be worthwhile, especially if such changes
7406 make the program work better.
7408 @node Aliasing Assumed To Work
7409 @subsection Aliasing Assumed To Work
7410 @cindex -falias-check option
7411 @cindex options, -falias-check
7412 @cindex -fargument-alias option
7413 @cindex options, -fargument-alias
7414 @cindex -fargument-noalias option
7415 @cindex options, -fargument-noalias
7416 @cindex -fno-argument-noalias-global option
7417 @cindex options, -fno-argument-noalias-global
7419 @cindex anti-aliasing
7420 @cindex overlapping arguments
7422 @cindex association, storage
7423 @cindex storage association
7424 @cindex scheduling of reads and writes
7425 @cindex reads and writes, scheduling
7427 The @option{-falias-check}, @option{-fargument-alias},
7428 @option{-fargument-noalias},
7429 and @option{-fno-argument-noalias-global} options,
7430 introduced in version 0.5.20 and
7431 @command{g77}'s version 2.7.2.2.f.2 of @command{gcc},
7432 were withdrawn as of @command{g77} version 0.5.23
7433 due to their not being supported by @command{gcc} version 2.8.
7435 These options control the assumptions regarding aliasing
7436 (overlapping) of writes and reads to main memory (core) made
7437 by the @command{gcc} back end.
7439 The information below still is useful, but applies to
7440 only those versions of @command{g77} that support the
7441 alias analysis implied by support for these options.
7443 These options are effective only when compiling with @option{-O}
7444 (specifying any level other than @option{-O0})
7445 or with @option{-falias-check}.
7447 The default for Fortran code is @option{-fargument-noalias-global}.
7448 (The default for C code and code written in other C-based languages
7449 is @option{-fargument-alias}.
7450 These defaults apply regardless of whether you use @command{g77} or
7451 @command{gcc} to compile your code.)
7453 Note that, on some systems, compiling with @option{-fforce-addr} in
7454 effect can produce more optimal code when the default aliasing
7455 options are in effect (and when optimization is enabled).
7457 If your program is not working when compiled with optimization,
7458 it is possible it is violating the Fortran standards (77 and 90)
7459 by relying on the ability to ``safely'' modify variables and
7460 arrays that are aliased, via procedure calls, to other variables
7461 and arrays, without using @code{EQUIVALENCE} to explicitly
7462 set up this kind of aliasing.
7464 (The FORTRAN 77 standard's prohibition of this sort of
7465 overlap, generally referred to therein as ``storage
7466 association'', appears in Sections 15.9.3.6.
7467 This prohibition allows implementations, such as @command{g77},
7468 to, for example, implement the passing of procedures and
7469 even values in @code{COMMON} via copy operations into local,
7470 perhaps more efficiently accessed temporaries at entry to a
7471 procedure, and, where appropriate, via copy operations back
7472 out to their original locations in memory at exit from that
7473 procedure, without having to take into consideration the
7474 order in which the local copies are updated by the code,
7475 among other things.)
7477 To test this hypothesis, try compiling your program with
7478 the @option{-fargument-alias} option, which causes the
7479 compiler to revert to assumptions essentially the same as
7480 made by versions of @command{g77} prior to 0.5.20.
7482 If the program works using this option, that strongly suggests
7483 that the bug is in your program.
7484 Finding and fixing the bug(s) should result in a program that
7485 is more standard-conforming and that can be compiled by @command{g77}
7486 in a way that results in a faster executable.
7488 (You might want to try compiling with @option{-fargument-noalias},
7489 a kind of half-way point, to see if the problem is limited to
7490 aliasing between dummy arguments and @code{COMMON} variables---this
7491 option assumes that such aliasing is not done, while still allowing
7492 aliasing among dummy arguments.)
7494 An example of aliasing that is invalid according to the standards
7495 is shown in the following program, which might @emph{not} produce
7496 the expected results when executed:
7504 SUBROUTINE FOO(J, K)
7511 The above program attempts to use the temporary aliasing of the
7512 @samp{J} and @samp{K} arguments in @samp{FOO} to effect a
7513 pathological behavior---the simultaneous changing of the values
7514 of @emph{both} @samp{J} and @samp{K} when either one of them
7517 The programmer likely expects the program to print these values:
7524 However, since the program is not standard-conforming, an
7525 implementation's behavior when running it is undefined, because
7526 subroutine @samp{FOO} modifies at least one of the arguments,
7527 and they are aliased with each other.
7528 (Even if one of the assignment statements was deleted, the
7529 program would still violate these rules.
7530 This kind of on-the-fly aliasing is permitted by the standard
7531 only when none of the aliased items are defined, or written,
7532 while the aliasing is in effect.)
7534 As a practical example, an optimizing compiler might schedule
7535 the @samp{J =} part of the second line of @samp{FOO} @emph{after}
7536 the reading of @samp{J} and @samp{K} for the @samp{J * K} expression,
7537 resulting in the following output:
7544 Essentially, compilers are promised (by the standard and, therefore,
7545 by programmers who write code they claim to be standard-conforming)
7546 that if they cannot detect aliasing via static analysis of a single
7547 program unit's @code{EQUIVALENCE} and @code{COMMON} statements, no
7548 such aliasing exists.
7549 In such cases, compilers are free to assume that an assignment to
7550 one variable will not change the value of another variable, allowing
7551 it to avoid generating code to re-read the value of the other
7552 variable, to re-schedule reads and writes, and so on, to produce
7553 a faster executable.
7555 The same promise holds true for arrays (as seen by the called
7556 procedure)---an element of one dummy array cannot be aliased
7557 with, or overlap, any element of another dummy array or be
7558 in a @code{COMMON} area known to the procedure.
7560 (These restrictions apply only when the procedure defines, or
7561 writes to, one of the aliased variables or arrays.)
7563 Unfortunately, there is no way to find @emph{all} possible cases of
7564 violations of the prohibitions against aliasing in Fortran code.
7565 Static analysis is certainly imperfect, as is run-time analysis,
7566 since neither can catch all violations.
7567 (Static analysis can catch all likely violations, and some that
7568 might never actually happen, while run-time analysis can catch
7569 only those violations that actually happen during a particular run.
7570 Neither approach can cope with programs mixing Fortran code with
7571 routines written in other languages, however.)
7573 Currently, @command{g77} provides neither static nor run-time facilities
7574 to detect any cases of this problem, although other products might.
7575 Run-time facilities are more likely to be offered by future
7576 versions of @command{g77}, though patches improving @command{g77} so that
7577 it provides either form of detection are welcome.
7579 @node Output Assumed To Flush
7580 @subsection Output Assumed To Flush
7581 @cindex ALWAYS_FLUSH
7582 @cindex synchronous write errors
7584 @cindex flushing output
7586 @cindex I/O, flushing
7587 @cindex output, flushing
7588 @cindex writes, flushing
7590 @cindex network file system
7592 For several versions prior to 0.5.20, @command{g77} configured its
7593 version of the @code{libf2c} run-time library so that one of
7594 its configuration macros, @code{ALWAYS_FLUSH}, was defined.
7596 This was done as a result of a belief that many programs expected
7597 output to be flushed to the operating system (under UNIX, via
7598 the @code{fflush()} library call) with the result that errors,
7599 such as disk full, would be immediately flagged via the
7600 relevant @code{ERR=} and @code{IOSTAT=} mechanism.
7602 Because of the adverse effects this approach had on the performance
7603 of many programs, @command{g77} no longer configures @code{libf2c}
7604 (now named @code{libg2c} in its @command{g77} incarnation)
7605 to always flush output.
7607 If your program depends on this behavior, either insert the
7608 appropriate @samp{CALL FLUSH} statements, or modify the sources
7609 to the @code{libg2c}, rebuild and reinstall @command{g77}, and
7610 relink your programs with the modified library.
7612 (Ideally, @code{libg2c} would offer the choice at run-time, so
7613 that a compile-time option to @command{g77} or @command{f2c} could
7614 result in generating the appropriate calls to flushing or
7615 non-flushing library routines.)
7617 Some Fortran programs require output
7618 (writes) to be flushed to the operating system (under UNIX,
7619 via the @code{fflush()} library call) so that errors,
7620 such as disk full, are immediately flagged via the relevant
7621 @code{ERR=} and @code{IOSTAT=} mechanism, instead of such
7622 errors being flagged later as subsequent writes occur, forcing
7623 the previously written data to disk, or when the file is
7626 Essentially, the difference can be viewed as synchronous error
7627 reporting (immediate flagging of errors during writes) versus
7628 asynchronous, or, more precisely, buffered error reporting
7629 (detection of errors might be delayed).
7631 @code{libg2c} supports flagging write errors immediately when
7632 it is built with the @code{ALWAYS_FLUSH} macro defined.
7633 This results in a @code{libg2c} that runs slower, sometimes
7634 quite a bit slower, under certain circumstances---for example,
7635 accessing files via the networked file system NFS---but the
7636 effect can be more reliable, robust file I/O.
7638 If you know that Fortran programs requiring this level of precision
7639 of error reporting are to be compiled using the
7640 version of @command{g77} you are building, you might wish to
7641 modify the @command{g77} source tree so that the version of
7642 @code{libg2c} is built with the @code{ALWAYS_FLUSH} macro
7643 defined, enabling this behavior.
7645 To do this, find this line in @file{@value{path-libf2c}/f2c.h} in
7646 your @command{g77} source tree:
7649 /* #define ALWAYS_FLUSH */
7652 Remove the leading @samp{/*@w{ }},
7653 so the line begins with @samp{#define},
7654 and the trailing @samp{@w{ }*/}.
7656 Then build or rebuild @command{g77} as appropriate.
7658 @node Large File Unit Numbers
7659 @subsection Large File Unit Numbers
7661 @cindex unit numbers
7662 @cindex maximum unit number
7663 @cindex illegal unit number
7664 @cindex increasing maximum unit number
7666 If your program crashes at run time with a message including
7667 the text @samp{illegal unit number}, that probably is
7668 a message from the run-time library, @code{libg2c}.
7670 The message means that your program has attempted to use a
7671 file unit number that is out of the range accepted by
7673 Normally, this range is 0 through 99, and the high end
7674 of the range is controlled by a @code{libg2c} source-file
7675 macro named @code{MXUNIT}.
7677 If you can easily change your program to use unit numbers
7678 in the range 0 through 99, you should do so.
7680 As distributed, whether as part of @command{f2c} or @command{g77},
7681 @code{libf2c} accepts file unit numbers only in the range
7683 For example, a statement such as @samp{WRITE (UNIT=100)} causes
7684 a run-time crash in @code{libf2c}, because the unit number,
7685 100, is out of range.
7687 If you know that Fortran programs at your installation require
7688 the use of unit numbers higher than 99, you can change the
7689 value of the @code{MXUNIT} macro, which represents the maximum unit
7690 number, to an appropriately higher value.
7692 To do this, edit the file @file{@value{path-libf2c}/libI77/fio.h} in your
7693 @command{g77} source tree, changing the following line:
7699 Change the line so that the value of @code{MXUNIT} is defined to be
7700 at least one @emph{greater} than the maximum unit number used by
7701 the Fortran programs on your system.
7703 (For example, a program that does @samp{WRITE (UNIT=255)} would require
7704 @code{MXUNIT} set to at least 256 to avoid crashing.)
7706 Then build or rebuild @command{g77} as appropriate.
7708 @emph{Note:} Changing this macro has @emph{no} effect on other limits
7709 your system might place on the number of files open at the same time.
7710 That is, the macro might allow a program to do @samp{WRITE (UNIT=100)},
7711 but the library and operating system underlying @code{libf2c} might
7712 disallow it if many other files have already been opened (via @code{OPEN} or
7713 implicitly via @code{READ}, @code{WRITE}, and so on).
7714 Information on how to increase these other limits should be found
7715 in your system's documentation.
7717 @node Floating-point precision
7718 @subsection Floating-point precision
7720 @cindex IEEE 754 conformance
7721 @cindex conformance, IEEE 754
7722 @cindex floating-point, precision
7723 @cindex ix86 floating-point
7724 @cindex x86 floating-point
7725 If your program depends on exact IEEE 754 floating-point handling it may
7726 help on some systems---specifically x86 or m68k hardware---to use
7727 the @option{-ffloat-store} option or to reset the precision flag on the
7728 floating-point unit.
7729 @xref{Optimize Options}.
7731 However, it might be better simply to put the FPU into double precision
7732 mode and not take the performance hit of @option{-ffloat-store}. On x86
7733 and m68k GNU systems you can do this with a technique similar to that
7734 for turning on floating-point exceptions
7735 (@pxref{Floating-point Exception Handling}).
7736 The control word could be set to double precision by some code like this
7739 #include <fpu_control.h>
7741 fpu_control_t cw = (_FPU_DEFAULT & ~_FPU_EXTENDED) | _FPU_DOUBLE;
7745 (It is not clear whether this has any effect on the operation of the GNU
7746 maths library, but we have no evidence of it causing trouble.)
7748 Some targets (such as the Alpha) may need special options for full IEEE
7750 @xref{Submodel Options,,Hardware Models and Configurations,gcc,Using
7751 the GNU Compiler Collection (GCC)}.
7753 @node Inconsistent Calling Sequences
7754 @subsection Inconsistent Calling Sequences
7757 @cindex floating-point, errors
7758 @cindex ix86 FPU stack
7759 @cindex x86 FPU stack
7760 Code containing inconsistent calling sequences in the same file is
7761 normally rejected---see @ref{GLOBALS}.
7762 (Use, say, @command{ftnchek} to ensure
7763 consistency across source files.
7764 @xref{f2c Skeletons and Prototypes,,
7765 Generating Skeletons and Prototypes with @command{f2c}}.)
7767 Mysterious errors, which may appear to be code generation problems, can
7768 appear specifically on the x86 architecture with some such
7769 inconsistencies. On x86 hardware, floating-point return values of
7770 functions are placed on the floating-point unit's register stack, not
7771 the normal stack. Thus calling a @code{REAL} or @code{DOUBLE PRECISION}
7772 @code{FUNCTION} as some other sort of procedure, or vice versa,
7773 scrambles the floating-point stack. This may break unrelated code
7774 executed later. Similarly if, say, external C routines are written
7777 @node Overly Convenient Options
7778 @section Overly Convenient Command-line Options
7779 @cindex overly convenient options
7780 @cindex options, overly convenient
7782 These options should be used only as a quick-and-dirty way to determine
7783 how well your program will run under different compilation models
7784 without having to change the source.
7785 Some are more problematic
7786 than others, depending on how portable and maintainable you want the
7787 program to be (and, of course, whether you are allowed to change it
7790 You should not continue to use these command-line options to compile
7791 a given program, but rather should make changes to the source code:
7794 @cindex -finit-local-zero option
7795 @cindex options, -finit-local-zero
7796 @item -finit-local-zero
7797 (This option specifies that any uninitialized local variables
7798 and arrays have default initialization to binary zeros.)
7800 Many other compilers do this automatically, which means lots of
7801 Fortran code developed with those compilers depends on it.
7803 It is safer (and probably
7804 would produce a faster program) to find the variables and arrays that
7805 need such initialization and provide it explicitly via @code{DATA}, so that
7806 @option{-finit-local-zero} is not needed.
7808 Consider using @option{-Wuninitialized} (which requires @option{-O}) to
7809 find likely candidates, but
7810 do not specify @option{-finit-local-zero} or @option{-fno-automatic},
7811 or this technique won't work.
7813 @cindex -fno-automatic option
7814 @cindex options, -fno-automatic
7815 @item -fno-automatic
7816 (This option specifies that all local variables and arrays
7817 are to be treated as if they were named in @code{SAVE} statements.)
7819 Many other compilers do this automatically, which means lots of
7820 Fortran code developed with those compilers depends on it.
7822 The effect of this is that all non-automatic variables and arrays
7823 are made static, that is, not placed on the stack or in heap storage.
7824 This might cause a buggy program to appear to work better.
7825 If so, rather than relying on this command-line option (and hoping all
7826 compilers provide the equivalent one), add @code{SAVE}
7827 statements to some or all program unit sources, as appropriate.
7828 Consider using @option{-Wuninitialized} (which requires @option{-O})
7829 to find likely candidates, but
7830 do not specify @option{-finit-local-zero} or @option{-fno-automatic},
7831 or this technique won't work.
7833 The default is @option{-fautomatic}, which tells @command{g77} to try
7834 and put variables and arrays on the stack (or in fast registers)
7835 where possible and reasonable.
7836 This tends to make programs faster.
7838 @cindex automatic arrays
7839 @cindex arrays, automatic
7840 @emph{Note:} Automatic variables and arrays are not affected
7842 These are variables and arrays that are @emph{necessarily} automatic,
7843 either due to explicit statements, or due to the way they are
7845 Examples include local variables and arrays not given the
7846 @code{SAVE} attribute in procedures declared @code{RECURSIVE},
7847 and local arrays declared with non-constant bounds (automatic
7849 Currently, @command{g77} supports only automatic arrays, not
7850 @code{RECURSIVE} procedures or other means of explicitly
7851 specifying that variables or arrays are automatic.
7853 @cindex -f@var{group}-intrinsics-hide option
7854 @cindex options, -f@var{group}-intrinsics-hide
7855 @item -f@var{group}-intrinsics-hide
7856 Change the source code to use @code{EXTERNAL} for any external procedure
7857 that might be the name of an intrinsic.
7858 It is easy to find these using @option{-f@var{group}-intrinsics-disable}.
7861 @node Faster Programs
7862 @section Faster Programs
7863 @cindex speed, of programs
7864 @cindex programs, speeding up
7866 Aside from the usual @command{gcc} options, such as @option{-O},
7867 @option{-ffast-math}, and so on, consider trying some of the
7868 following approaches to speed up your program (once you get
7873 * Prefer Automatic Uninitialized Variables::
7874 * Avoid f2c Compatibility::
7875 * Use Submodel Options::
7879 @subsection Aligned Data
7881 @cindex data, aligned
7882 @cindex stack, aligned
7883 @cindex aligned data
7884 @cindex aligned stack
7885 @cindex Pentium optimizations
7886 @cindex optimization, for Pentium
7888 On some systems, such as those with Pentium Pro CPUs, programs
7889 that make heavy use of @code{REAL(KIND=2)} (@code{DOUBLE PRECISION})
7890 might run much slower
7891 than possible due to the compiler not aligning these 64-bit
7892 values to 64-bit boundaries in memory.
7893 (The effect also is present, though
7894 to a lesser extent, on the 586 (Pentium) architecture.)
7896 The Intel x86 architecture generally ensures that these programs will
7897 work on all its implementations,
7898 but particular implementations (such as Pentium Pro)
7899 perform better with more strict alignment.
7900 (Such behavior isn't unique to the Intel x86 architecture.)
7901 Other architectures might @emph{demand} 64-bit alignment
7904 There are a variety of approaches to use to address this problem:
7908 @cindex @code{COMMON} layout
7909 @cindex layout of @code{COMMON} blocks
7910 Order your @code{COMMON} and @code{EQUIVALENCE} areas such
7911 that the variables and arrays with the widest alignment
7912 guidelines come first.
7914 For example, on most systems, this would mean placing
7915 @code{COMPLEX(KIND=2)}, @code{REAL(KIND=2)}, and
7916 @code{INTEGER(KIND=2)} entities first, followed by @code{REAL(KIND=1)},
7917 @code{INTEGER(KIND=1)}, and @code{LOGICAL(KIND=1)} entities, then
7918 @code{INTEGER(KIND=6)} entities, and finally @code{CHARACTER}
7919 and @code{INTEGER(KIND=3)} entities.
7921 The reason to use such placement is it makes it more likely
7922 that your data will be aligned properly, without requiring
7923 you to do detailed analysis of each aggregate (@code{COMMON}
7924 and @code{EQUIVALENCE}) area.
7926 Specifically, on systems where the above guidelines are
7927 appropriate, placing @code{CHARACTER} entities before
7928 @code{REAL(KIND=2)} entities can work just as well,
7929 but only if the number of bytes occupied by the @code{CHARACTER}
7930 entities is divisible by the recommended alignment for
7931 @code{REAL(KIND=2)}.
7933 By ordering the placement of entities in aggregate
7934 areas according to the simple guidelines above, you
7935 avoid having to carefully count the number of bytes
7936 occupied by each entity to determine whether the
7937 actual alignment of each subsequent entity meets the
7938 alignment guidelines for the type of that entity.
7940 If you don't ensure correct alignment of @code{COMMON} elements, the
7941 compiler may be forced by some systems to violate the Fortran semantics by
7942 adding padding to get @code{DOUBLE PRECISION} data properly aligned.
7943 If the unfortunate practice is employed of overlaying different types of
7944 data in the @code{COMMON} block, the different variants
7945 of this block may become misaligned with respect to each other.
7946 Even if your platform doesn't require strict alignment,
7947 @code{COMMON} should be laid out as above for portability.
7948 (Unfortunately the FORTRAN 77 standard didn't anticipate this
7949 possible requirement, which is compiler-independent on a given platform.)
7952 @cindex -malign-double option
7953 @cindex options, -malign-double
7954 Use the (x86-specific) @option{-malign-double} option when compiling
7955 programs for the Pentium and Pentium Pro architectures (called 586
7956 and 686 in the @command{gcc} configuration subsystem).
7957 The warning about this in the @command{gcc} manual isn't
7958 generally relevant to Fortran,
7959 but using it will force @code{COMMON} to be padded if necessary to align
7960 @code{DOUBLE PRECISION} data.
7962 When @code{DOUBLE PRECISION} data is forcibly aligned
7963 in @code{COMMON} by @command{g77} due to specifying @option{-malign-double},
7964 @command{g77} issues a warning about the need to
7967 In this case, each and every program unit that uses
7968 the same @code{COMMON} area
7969 must specify the same layout of variables and their types
7971 and be compiled with @option{-malign-double} as well.
7972 @command{g77} will issue warnings in each case,
7973 but as long as every program unit using that area
7974 is compiled with the same warnings,
7975 the resulting object files should work when linked together
7976 unless the program makes additional assumptions about
7977 @code{COMMON} area layouts that are outside the scope
7978 of the FORTRAN 77 standard,
7979 or uses @code{EQUIVALENCE} or different layouts
7980 in ways that assume no padding is ever inserted by the compiler.
7983 Ensure that @file{crt0.o} or @file{crt1.o}
7984 on your system guarantees a 64-bit
7985 aligned stack for @code{main()}.
7986 The recent one from GNU (@code{glibc2}) will do this on x86 systems,
7987 but we don't know of any other x86 setups where it will be right.
7988 Read your system's documentation to determine if
7989 it is appropriate to upgrade to a more recent version
7990 to obtain the optimal alignment.
7993 Progress is being made on making this work
7994 ``out of the box'' on future versions of @command{g77},
7995 @command{gcc}, and some of the relevant operating systems
7996 (such as GNU/Linux).
7998 @node Prefer Automatic Uninitialized Variables
7999 @subsection Prefer Automatic Uninitialized Variables
8001 If you're using @option{-fno-automatic} already, you probably
8002 should change your code to allow compilation with @option{-fautomatic}
8003 (the default), to allow the program to run faster.
8005 Similarly, you should be able to use @option{-fno-init-local-zero}
8006 (the default) instead of @option{-finit-local-zero}.
8007 This is because it is rare that every variable affected by these
8008 options in a given program actually needs to
8011 For example, @option{-fno-automatic}, which effectively @code{SAVE}s
8012 every local non-automatic variable and array, affects even things like
8014 variables, which rarely need to be @code{SAVE}d, and this often reduces
8015 run-time performances.
8016 Similarly, @option{-fno-init-local-zero} forces such
8017 variables to be initialized to zero---when @code{SAVE}d (such as when
8018 @option{-fno-automatic}), this by itself generally affects only
8019 startup time for a program, but when not @code{SAVE}d,
8020 it can slow down the procedure every time it is called.
8022 @xref{Overly Convenient Options,,Overly Convenient Command-Line Options},
8023 for information on the @option{-fno-automatic} and
8024 @option{-finit-local-zero} options and how to convert
8025 their use into selective changes in your own code.
8027 @node Avoid f2c Compatibility
8028 @subsection Avoid f2c Compatibility
8029 @cindex -fno-f2c option
8030 @cindex options, -fno-f2c
8031 @cindex @command{f2c} compatibility
8032 @cindex compatibility, @command{f2c}
8034 If you aren't linking with any code compiled using
8035 @command{f2c}, try using the @option{-fno-f2c} option when
8036 compiling @emph{all} the code in your program.
8037 (Note that @code{libf2c} is @emph{not} an example of code
8038 that is compiled using @command{f2c}---it is compiled by a C
8039 compiler, typically @command{gcc}.)
8041 @node Use Submodel Options
8042 @subsection Use Submodel Options
8045 Using an appropriate @option{-m} option to generate specific code for your
8046 CPU may be worthwhile, though it may mean the executable won't run on
8047 other versions of the CPU that don't support the same instruction set.
8048 @xref{Submodel Options,,Hardware Models and Configurations,gcc,Using the
8049 GNU Compiler Collection (GCC)}. For instance on an x86 system the
8051 been built---as shown by @samp{g77 -v}---for the target
8052 @samp{i386-pc-linux-gnu}, i.e.@: an @samp{i386} CPU@. In that case to
8053 generate code best optimized for a Pentium you could use the option
8054 @option{-march=pentium}.
8056 For recent CPUs that don't have explicit support in the released version
8057 of @command{gcc}, it @emph{might} still be possible to get improvements
8058 with certain @option{-m} options.
8060 @option{-fomit-frame-pointer} can help performance on x86 systems and
8061 others. It will, however, inhibit debugging on the systems on which it
8062 is not turned on anyway by @option{-O}.
8065 @chapter Known Causes of Trouble with GNU Fortran
8067 @cindex installation trouble
8068 @cindex known causes of trouble
8070 This section describes known problems that affect users of GNU Fortran.
8071 Most of these are not GNU Fortran bugs per se---if they were, we would
8073 But the result for a user might be like the result of a bug.
8075 Some of these problems are due to bugs in other software, some are
8076 missing features that are too much work to add, and some are places
8077 where people's opinions differ as to what is best.
8079 (Note that some of this portion of the manual is lifted
8080 directly from the @command{gcc} manual, with minor modifications
8081 to tailor it to users of @command{g77}.
8082 Anytime a bug seems to have more to do with the @command{gcc}
8083 portion of @command{g77}, see
8084 @ref{Trouble,,Known Causes of Trouble with GCC,
8085 gcc,Using the GNU Compiler Collection (GCC)}.)
8088 * But-bugs:: Bugs really in other programs or elsewhere.
8089 * Known Bugs:: Bugs known to be in this version of @command{g77}.
8090 * Missing Features:: Features we already know we want to add later.
8091 * Disappointments:: Regrettable things we can't change.
8092 * Non-bugs:: Things we think are right, but some others disagree.
8093 * Warnings and Errors:: Which problems in your code get warnings,
8094 and which get errors.
8098 @section Bugs Not In GNU Fortran
8101 These are bugs to which the maintainers often have to reply,
8102 ``but that isn't a bug in @command{g77}@dots{}''.
8103 Some of these already are fixed in new versions of other
8104 software; some still need to be fixed; some are problems
8105 with how @command{g77} is installed or is being used;
8106 some are the result of bad hardware that causes software
8107 to misbehave in sometimes bizarre ways;
8108 some just cannot be addressed at this time until more
8109 is known about the problem.
8111 Please don't re-report these bugs to the @command{g77} maintainers---if
8112 you must remind someone how important it is to you that the problem
8113 be fixed, talk to the people responsible for the other products
8114 identified below, but preferably only after you've tried the
8115 latest versions of those products.
8116 The @command{g77} maintainers have their hands full working on
8117 just fixing and improving @command{g77}, without serving as a
8118 clearinghouse for all bugs that happen to affect @command{g77}
8121 @xref{Collected Fortran Wisdom}, for information on behavior
8122 of Fortran programs, and the programs that compile them, that
8123 might be @emph{thought} to indicate bugs.
8126 * Signal 11 and Friends:: Strange behavior by any software.
8127 * Cannot Link Fortran Programs:: Unresolved references.
8128 * Large Common Blocks:: Problems on older GNU/Linux systems.
8129 * Debugger Problems:: When the debugger crashes.
8130 * NeXTStep Problems:: Misbehaving executables.
8131 * Stack Overflow:: More misbehaving executables.
8132 * Nothing Happens:: Less behaving executables.
8133 * Strange Behavior at Run Time:: Executables misbehaving due to
8134 bugs in your program.
8135 * Floating-point Errors:: The results look wrong, but@dots{}.
8138 @node Signal 11 and Friends
8139 @subsection Signal 11 and Friends
8141 @cindex hardware errors
8143 A whole variety of strange behaviors can occur when the
8144 software, or the way you are using the software,
8145 stresses the hardware in a way that triggers hardware bugs.
8146 This might seem hard to believe, but it happens frequently
8147 enough that there exist documents explaining in detail
8148 what the various causes of the problems are, what
8149 typical symptoms look like, and so on.
8151 Generally these problems are referred to in this document
8152 as ``signal 11'' crashes, because the Linux kernel, running
8153 on the most popular hardware (the Intel x86 line), often
8154 stresses the hardware more than other popular operating
8156 When hardware problems do occur under GNU/Linux on x86
8157 systems, these often manifest themselves as ``signal 11''
8158 problems, as illustrated by the following diagnostic:
8161 sh# @kbd{g77 myprog.f}
8162 gcc: Internal compiler error: program f771 got fatal signal 11
8166 It is @emph{very} important to remember that the above
8167 message is @emph{not} the only one that indicates a
8168 hardware problem, nor does it always indicate a hardware
8171 In particular, on systems other than those running the Linux
8172 kernel, the message might appear somewhat or very different,
8173 as it will if the error manifests itself while running a
8174 program other than the @command{g77} compiler.
8176 it will appear somewhat different when running your program,
8177 when running Emacs, and so on.
8179 How to cope with such problems is well beyond the scope
8182 However, users of Linux-based systems (such as GNU/Linux)
8183 should review @uref{http://www.bitwizard.nl/sig11/}, a source
8184 of detailed information on diagnosing hardware problems,
8185 by recognizing their common symptoms.
8187 Users of other operating systems and hardware might
8188 find this reference useful as well.
8189 If you know of similar material for another hardware/software
8190 combination, please let us know so we can consider including
8191 a reference to it in future versions of this manual.
8193 @node Cannot Link Fortran Programs
8194 @subsection Cannot Link Fortran Programs
8195 @cindex unresolved reference (various)
8196 @cindex linking error for user code
8198 @cindex @command{ld}, error linking user code
8199 @cindex @command{ld}, can't find strange names
8200 On some systems, perhaps just those with out-of-date (shared?)
8201 libraries, unresolved-reference errors happen when linking @command{g77}-compiled
8202 programs (which should be done using @command{g77}).
8204 If this happens to you, try appending @option{-lc} to the command you
8205 use to link the program, e.g. @samp{g77 foo.f -lc}.
8206 @command{g77} already specifies @samp{-lg2c -lm} when it calls the linker,
8207 but it cannot also specify @option{-lc} because not all systems have a
8208 file named @file{libc.a}.
8210 It is unclear at this point whether there are legitimately installed
8211 systems where @samp{-lg2c -lm} is insufficient to resolve code produced
8214 @cindex undefined reference (_main)
8215 @cindex linking error, user code
8216 @cindex @command{ld}, error linking user code
8218 @cindex @command{ld}, can't find @samp{_main}
8219 If your program doesn't link due to unresolved references to names
8220 like @samp{_main}, make sure you're using the @command{g77} command to do the
8221 link, since this command ensures that the necessary libraries are
8222 loaded by specifying @samp{-lg2c -lm} when it invokes the @command{gcc}
8223 command to do the actual link.
8224 (Use the @option{-v} option to discover
8225 more about what actually happens when you use the @command{g77} and @command{gcc}
8228 Also, try specifying @option{-lc} as the last item on the @command{g77}
8229 command line, in case that helps.
8231 @node Large Common Blocks
8232 @subsection Large Common Blocks
8233 @cindex common blocks, large
8234 @cindex large common blocks
8235 @cindex linking, errors
8236 @cindex @command{ld}, errors
8237 @cindex errors, linker
8238 On some older GNU/Linux systems, programs with common blocks larger
8239 than 16MB cannot be linked without some kind of error
8240 message being produced.
8242 This is a bug in older versions of @command{ld}, fixed in
8243 more recent versions of @code{binutils}, such as version 2.6.
8245 @node Debugger Problems
8246 @subsection Debugger Problems
8247 @cindex @command{gdb}, support
8248 @cindex support, @command{gdb}
8249 There are some known problems when using @command{gdb} on code
8250 compiled by @command{g77}.
8251 Inadequate investigation as of the release of 0.5.16 results in not
8252 knowing which products are the culprit, but @file{gdb-4.14} definitely
8253 crashes when, for example, an attempt is made to print the contents
8254 of a @code{COMPLEX(KIND=2)} dummy array, on at least some GNU/Linux
8255 machines, plus some others.
8256 Attempts to access assumed-size arrays are
8257 also known to crash recent versions of @command{gdb}.
8258 (@command{gdb}'s Fortran support was done for a different compiler
8259 and isn't properly compatible with @command{g77}.)
8261 @node NeXTStep Problems
8262 @subsection NeXTStep Problems
8263 @cindex NeXTStep problems
8265 @cindex segmentation violation
8266 Developers of Fortran code on NeXTStep (all architectures) have to
8267 watch out for the following problem when writing programs with
8268 large, statically allocated (i.e. non-stack based) data structures
8269 (common blocks, saved arrays).
8271 Due to the way the native loader (@file{/bin/ld}) lays out
8272 data structures in virtual memory, it is very easy to create an
8273 executable wherein the @samp{__DATA} segment overlaps (has addresses in
8274 common) with the @samp{UNIX STACK} segment.
8276 This leads to all sorts of trouble, from the executable simply not
8277 executing, to bus errors.
8278 The NeXTStep command line tool @command{ebadexec} points to
8279 the problem as follows:
8282 % @kbd{/bin/ebadexec a.out}
8283 /bin/ebadexec: __LINKEDIT segment (truncated address = 0x3de000
8284 rounded size = 0x2a000) of executable file: a.out overlaps with UNIX
8285 STACK segment (truncated address = 0x400000 rounded size =
8286 0x3c00000) of executable file: a.out
8289 (In the above case, it is the @samp{__LINKEDIT} segment that overlaps the
8292 This can be cured by assigning the @samp{__DATA} segment
8293 (virtual) addresses beyond the stack segment.
8295 estimate for this is from address 6000000 (hexadecimal) onwards---this
8296 has always worked for me [Toon Moene]:
8299 % @kbd{g77 -segaddr __DATA 6000000 test.f}
8300 % @kbd{ebadexec a.out}
8301 ebadexec: file: a.out appears to be executable
8305 Browsing through @file{@value{path-g77}/Makefile.in},
8306 you will find that the @code{f771} program itself also has to be
8307 linked with these flags---it has large statically allocated
8309 (Version 0.5.18 reduces this somewhat, but probably
8312 (The above item was contributed by Toon Moene
8313 (@email{toon@@moene.indiv.nluug.nl}).)
8315 @node Stack Overflow
8316 @subsection Stack Overflow
8317 @cindex stack, overflow
8318 @cindex segmentation violation
8319 @command{g77} code might fail at runtime (probably with a ``segmentation
8320 violation'') due to overflowing the stack.
8321 This happens most often on systems with an environment
8322 that provides substantially more heap space (for use
8323 when arbitrarily allocating and freeing memory) than stack
8326 Often this can be cured by
8327 increasing or removing your shell's limit on stack usage, typically
8328 using @kbd{limit stacksize} (in @command{csh} and derivatives) or
8329 @kbd{ulimit -s} (in @command{sh} and derivatives).
8331 Increasing the allowed stack size might, however, require
8332 changing some operating system or system configuration parameters.
8334 You might be able to work around the problem by compiling with the
8335 @option{-fno-automatic} option to reduce stack usage, probably at the
8338 @command{g77}, on most machines, puts many variables and arrays on the stack
8339 where possible, and can be configured (by changing
8340 @code{FFECOM_sizeMAXSTACKITEM} in @file{@value{path-g77}/com.c}) to force
8341 smaller-sized entities into static storage (saving
8342 on stack space) or permit larger-sized entities to be put on the
8343 stack (which can improve run-time performance, as it presents
8344 more opportunities for the GBE to optimize the generated code).
8346 @emph{Note:} Putting more variables and arrays on the stack
8347 might cause problems due to system-dependent limits on stack size.
8348 Also, the value of @code{FFECOM_sizeMAXSTACKITEM} has no
8349 effect on automatic variables and arrays.
8350 @xref{But-bugs}, for more information.
8351 @emph{Note:} While @code{libg2c} places a limit on the range
8352 of Fortran file-unit numbers, the underlying library and operating
8353 system might impose different kinds of limits.
8354 For example, some systems limit the number of files simultaneously
8355 open by a running program.
8356 Information on how to increase these limits should be found
8357 in your system's documentation.
8359 @cindex automatic arrays
8360 @cindex arrays, automatic
8361 However, if your program uses large automatic arrays
8362 (for example, has declarations like @samp{REAL A(N)} where
8363 @samp{A} is a local array and @samp{N} is a dummy or
8364 @code{COMMON} variable that can have a large value),
8365 neither use of @option{-fno-automatic},
8366 nor changing the cut-off point for @command{g77} for using the stack,
8367 will solve the problem by changing the placement of these
8368 large arrays, as they are @emph{necessarily} automatic.
8370 @command{g77} currently provides no means to specify that
8371 automatic arrays are to be allocated on the heap instead
8373 So, other than increasing the stack size, your best bet is to
8374 change your source code to avoid large automatic arrays.
8375 Methods for doing this currently are outside the scope of
8378 (@emph{Note:} If your system puts stack and heap space in the
8379 same memory area, such that they are effectively combined, then
8380 a stack overflow probably indicates a program that is either
8381 simply too large for the system, or buggy.)
8383 @node Nothing Happens
8384 @subsection Nothing Happens
8385 @cindex nothing happens
8386 @cindex naming programs
8387 @cindex @command{test} programs
8388 @cindex programs, @command{test}
8389 It is occasionally reported that a ``simple'' program,
8390 such as a ``Hello, World!'' program, does nothing when
8391 it is run, even though the compiler reported no errors,
8392 despite the program containing nothing other than a
8393 simple @code{PRINT} statement.
8395 This most often happens because the program has been
8396 compiled and linked on a UNIX system and named @command{test},
8397 though other names can lead to similarly unexpected
8398 run-time behavior on various systems.
8400 Essentially this problem boils down to giving
8401 your program a name that is already known to
8402 the shell you are using to identify some other program,
8403 which the shell continues to execute instead of your
8404 program when you invoke it via, for example:
8411 Under UNIX and many other system, a simple command name
8412 invokes a searching mechanism that might well not choose
8413 the program located in the current working directory if
8414 there is another alternative (such as the @command{test}
8415 command commonly installed on UNIX systems).
8417 The reliable way to invoke a program you just linked in
8418 the current directory under UNIX is to specify it using
8419 an explicit pathname, as in:
8427 Users who encounter this problem should take the time to
8428 read up on how their shell searches for commands, how to
8429 set their search path, and so on.
8430 The relevant UNIX commands to learn about include
8431 @command{man}, @command{info} (on GNU systems), @command{setenv} (or
8432 @command{set} and @command{env}), @command{which}, and @command{find}.
8434 @node Strange Behavior at Run Time
8435 @subsection Strange Behavior at Run Time
8436 @cindex segmentation violation
8438 @cindex overwritten data
8439 @cindex data, overwritten
8440 @command{g77} code might fail at runtime with ``segmentation violation'',
8441 ``bus error'', or even something as subtle as a procedure call
8442 overwriting a variable or array element that it is not supposed
8445 These can be symptoms of a wide variety of actual bugs that
8446 occurred earlier during the program's run, but manifested
8447 themselves as @emph{visible} problems some time later.
8449 Overflowing the bounds of an array---usually by writing beyond
8450 the end of it---is one of two kinds of bug that often occurs
8452 (Compile your code with the @option{-fbounds-check} option
8453 to catch many of these kinds of errors at program run time.)
8455 The other kind of bug is a mismatch between the actual arguments
8456 passed to a procedure and the dummy arguments as declared by that
8459 Both of these kinds of bugs, and some others as well, can be
8460 difficult to track down, because the bug can change its behavior,
8461 or even appear to not occur, when using a debugger.
8463 That is, these bugs can be quite sensitive to data, including
8464 data representing the placement of other data in memory (that is,
8465 pointers, such as the placement of stack frames in memory).
8467 @command{g77} now offers the
8468 ability to catch and report some of these problems at compile, link, or
8469 run time, such as by generating code to detect references to
8470 beyond the bounds of most arrays (except assumed-size arrays),
8471 and checking for agreement between calling and called procedures.
8472 Future improvements are likely to be made in the procedure-mismatch area,
8475 In the meantime, finding and fixing the programming
8476 bugs that lead to these behaviors is, ultimately, the user's
8477 responsibility, as difficult as that task can sometimes be.
8479 @cindex infinite spaces printed
8480 @cindex space, endless printing of
8481 @cindex libc, non-ANSI or non-default
8483 @cindex linking against non-standard library
8485 One runtime problem that has been observed might have a simple solution.
8486 If a formatted @code{WRITE} produces an endless stream of spaces, check
8487 that your program is linked against the correct version of the C library.
8488 The configuration process takes care to account for your
8489 system's normal @file{libc} not being ANSI-standard, which will
8490 otherwise cause this behavior.
8491 If your system's default library is
8492 ANSI-standard and you subsequently link against a non-ANSI one, there
8493 might be problems such as this one.
8495 Specifically, on Solaris2 systems,
8496 avoid picking up the @code{BSD} library from @file{/usr/ucblib}.
8498 @node Floating-point Errors
8499 @subsection Floating-point Errors
8500 @cindex floating-point errors
8501 @cindex rounding errors
8502 @cindex inconsistent floating-point results
8503 @cindex results, inconsistent
8504 Some programs appear to produce inconsistent floating-point
8505 results compiled by @command{g77} versus by other compilers.
8507 Often the reason for this behavior is the fact that floating-point
8508 values are represented on almost all Fortran systems by
8509 @emph{approximations}, and these approximations are inexact
8510 even for apparently simple values like 0.1, 0.2, 0.3, 0.4, 0.6,
8511 0.7, 0.8, 0.9, 1.1, and so on.
8512 Most Fortran systems, including all current ports of @command{g77},
8513 use binary arithmetic to represent these approximations.
8515 Therefore, the exact value of any floating-point approximation
8516 as manipulated by @command{g77}-compiled code is representable by
8517 adding some combination of the values 1.0, 0.5, 0.25, 0.125, and
8518 so on (just keep dividing by two) through the precision of the
8519 fraction (typically around 23 bits for @code{REAL(KIND=1)}, 52 for
8520 @code{REAL(KIND=2)}), then multiplying the sum by a integral
8521 power of two (in Fortran, by @samp{2**N}) that typically is between
8522 -127 and +128 for @code{REAL(KIND=1)} and -1023 and +1024 for
8523 @code{REAL(KIND=2)}, then multiplying by -1 if the number
8526 So, a value like 0.2 is exactly represented in decimal---since
8527 it is a fraction, @samp{2/10}, with a denominator that is compatible
8528 with the base of the number system (base 10).
8529 However, @samp{2/10} cannot be represented by any finite number
8530 of sums of any of 1.0, 0.5, 0.25, and so on, so 0.2 cannot
8531 be exactly represented in binary notation.
8533 (On the other hand, decimal notation can represent any binary
8534 number in a finite number of digits.
8535 Decimal notation cannot do so with ternary, or base-3,
8536 notation, which would represent floating-point numbers as
8537 sums of any of @samp{1/1}, @samp{1/3}, @samp{1/9}, and so on.
8538 After all, no finite number of decimal digits can exactly
8539 represent @samp{1/3}.
8540 Fortunately, few systems use ternary notation.)
8542 Moreover, differences in the way run-time I/O libraries convert
8543 between these approximations and the decimal representation often
8544 used by programmers and the programs they write can result in
8545 apparent differences between results that do not actually exist,
8546 or exist to such a small degree that they usually are not worth
8549 For example, consider the following program:
8556 When compiled by @command{g77}, the above program might output
8557 @samp{0.20000003}, while another compiler might produce a
8558 executable that outputs @samp{0.2}.
8560 This particular difference is due to the fact that, currently,
8561 conversion of floating-point values by the @code{libg2c} library,
8562 used by @command{g77}, handles only double-precision values.
8564 Since @samp{0.2} in the program is a single-precision value, it
8565 is converted to double precision (still in binary notation)
8566 before being converted back to decimal.
8567 The conversion to binary appends @emph{binary} zero digits to the
8568 original value---which, again, is an inexact approximation of
8569 0.2---resulting in an approximation that is much less exact
8570 than is connoted by the use of double precision.
8572 (The appending of binary zero digits has essentially the same
8573 effect as taking a particular decimal approximation of
8574 @samp{1/3}, such as @samp{0.3333333}, and appending decimal
8575 zeros to it, producing @samp{0.33333330000000000}.
8576 Treating the resulting decimal approximation as if it really
8577 had 18 or so digits of valid precision would make it seem
8578 a very poor approximation of @samp{1/3}.)
8580 As a result of converting the single-precision approximation
8581 to double precision by appending binary zeros, the conversion
8582 of the resulting double-precision
8583 value to decimal produces what looks like an incorrect
8584 result, when in fact the result is @emph{inexact}, and
8585 is probably no less inaccurate or imprecise an approximation
8586 of 0.2 than is produced by other compilers that happen to output
8587 the converted value as ``exactly'' @samp{0.2}.
8588 (Some compilers behave in a way that can make them appear
8589 to retain more accuracy across a conversion of a single-precision
8590 constant to double precision.
8591 @xref{Context-Sensitive Constants}, to see why
8592 this practice is illusory and even dangerous.)
8594 Note that a more exact approximation of the constant is
8595 computed when the program is changed to specify a
8596 double-precision constant:
8603 Future versions of @command{g77} and/or @code{libg2c} might convert
8604 single-precision values directly to decimal,
8605 instead of converting them to double precision first.
8606 This would tend to result in output that is more consistent
8607 with that produced by some other Fortran implementations.
8609 A useful source of information on floating-point computation is David
8610 Goldberg, `What Every Computer Scientist Should Know About
8611 Floating-Point Arithmetic', Computing Surveys, 23, March 1991, pp.@:
8613 An online version is available at
8614 @uref{http://docs.sun.com/}.
8616 Information related to the IEEE 754
8617 floating-point standard by a leading light can be found at
8618 @uref{http://http.cs.berkeley.edu/%7Ewkahan/ieee754status/};
8619 see also slides from the short course referenced from
8620 @uref{http://http.cs.berkeley.edu/%7Efateman/}.
8622 The supplement to the PostScript-formatted Goldberg document,
8623 referenced above, is available in HTML format.
8624 See `Differences Among IEEE 754 Implementations' by Doug Priest.
8625 This document explores some of the issues surrounding computing
8626 of extended (80-bit) results on processors such as the x86,
8627 especially when those results are arbitrarily truncated
8628 to 32-bit or 64-bit values by the compiler
8631 @cindex spills of floating-point results
8632 @cindex 80-bit spills
8633 @cindex truncation, of floating-point values
8634 (@emph{Note:} @command{g77} specifically, and @command{gcc} generally,
8635 does arbitrarily truncate 80-bit results during spills
8637 It is not yet clear whether a future version of
8638 the GNU compiler suite will offer 80-bit spills
8639 as an option, or perhaps even as the default behavior.)
8641 @c xref would be different between editions:
8642 The GNU C library provides routines for controlling the FPU, and other
8643 documentation about this.
8645 @xref{Floating-point precision}, regarding IEEE 754 conformance.
8649 @node Missing Features
8650 @section Missing Features
8652 This section lists features we know are missing from @command{g77},
8653 and which we want to add someday.
8654 (There is no priority implied in the ordering below.)
8657 GNU Fortran language:
8658 * Better Source Model::
8659 * Fortran 90 Support::
8660 * Intrinsics in PARAMETER Statements::
8661 * Arbitrary Concatenation::
8662 * SELECT CASE on CHARACTER Type::
8663 * RECURSIVE Keyword::
8664 * Popular Non-standard Types::
8665 * Full Support for Compiler Types::
8666 * Array Bounds Expressions::
8667 * POINTER Statements::
8668 * Sensible Non-standard Constructs::
8669 * READONLY Keyword::
8671 * Expressions in FORMAT Statements::
8672 * Explicit Assembler Code::
8673 * Q Edit Descriptor::
8675 GNU Fortran dialects:
8676 * Old-style PARAMETER Statements::
8677 * TYPE and ACCEPT I/O Statements::
8678 * STRUCTURE UNION RECORD MAP::
8679 * OPEN CLOSE and INQUIRE Keywords::
8680 * ENCODE and DECODE::
8681 * AUTOMATIC Statement::
8682 * Suppressing Space Padding::
8683 * Fortran Preprocessor::
8684 * Bit Operations on Floating-point Data::
8685 * Really Ugly Character Assignments::
8689 * Floating-point Exception Handling::
8690 * Nonportable Conversions::
8691 * Large Automatic Arrays::
8692 * Support for Threads::
8693 * Increasing Precision/Range::
8694 * Enabling Debug Lines::
8698 * Gracefully Handle Sensible Bad Code::
8699 * Non-standard Conversions::
8700 * Non-standard Intrinsics::
8701 * Modifying DO Variable::
8702 * Better Pedantic Compilation::
8703 * Warn About Implicit Conversions::
8704 * Invalid Use of Hollerith Constant::
8705 * Dummy Array Without Dimensioning Dummy::
8706 * Invalid FORMAT Specifiers::
8707 * Ambiguous Dialects::
8709 * Informational Messages::
8711 Run-time facilities:
8712 * Uninitialized Variables at Run Time::
8713 * Portable Unformatted Files::
8714 * Better List-directed I/O::
8715 * Default to Console I/O::
8718 * Labels Visible to Debugger::
8721 @node Better Source Model
8722 @subsection Better Source Model
8724 @command{g77} needs to provide, as the default source-line model,
8725 a ``pure visual'' mode, where
8726 the interpretation of a source program in this mode can be accurately
8727 determined by a user looking at a traditionally displayed rendition
8728 of the program (assuming the user knows whether the program is fixed
8731 The design should assume the user cannot tell tabs from spaces
8732 and cannot see trailing spaces on lines, but has canonical tab stops
8733 and, for fixed-form source, has the ability to always know exactly
8734 where column 72 is (since the Fortran standard itself requires
8735 this for fixed-form source).
8737 This would change the default treatment of fixed-form source
8738 to not treat lines with tabs as if they were infinitely long---instead,
8739 they would end at column 72 just as if the tabs were replaced
8740 by spaces in the canonical way.
8742 As part of this, provide common alternate models (Digital, @command{f2c},
8743 and so on) via command-line options.
8744 This includes allowing arbitrarily long
8745 lines for free-form source as well as fixed-form source and providing
8746 various limits and diagnostics as appropriate.
8748 @cindex sequence numbers
8749 @cindex columns 73 through 80
8750 Also, @command{g77} should offer, perhaps even default to, warnings
8751 when characters beyond the last valid column are anything other
8753 This would mean code with ``sequence numbers'' in columns 73 through 80
8754 would be rejected, and there's a lot of that kind of code around,
8755 but one of the most frequent bugs encountered by new users is
8756 accidentally writing fixed-form source code into and beyond
8758 So, maybe the users of old code would be able to more easily handle
8759 having to specify, say, a @option{-Wno-col73to80} option.
8761 @node Fortran 90 Support
8762 @subsection Fortran 90 Support
8763 @cindex Fortran 90, support
8764 @cindex support, Fortran 90
8766 @command{g77} does not support many of the features that
8767 distinguish Fortran 90 (and, now, Fortran 95) from
8770 Some Fortran 90 features are supported, because they
8771 make sense to offer even to die-hard users of F77.
8772 For example, many of them codify various ways F77 has
8773 been extended to meet users' needs during its tenure,
8774 so @command{g77} might as well offer them as the primary
8775 way to meet those same needs, even if it offers compatibility
8776 with one or more of the ways those needs were met
8777 by other F77 compilers in the industry.
8779 Still, many important F90 features are not supported,
8780 because no attempt has been made to research each and
8781 every feature and assess its viability in @command{g77}.
8782 In the meantime, users who need those features must
8783 use Fortran 90 compilers anyway, and the best approach
8784 to adding some F90 features to GNU Fortran might well be
8785 to fund a comprehensive project to create GNU Fortran 95.
8787 @node Intrinsics in PARAMETER Statements
8788 @subsection Intrinsics in @code{PARAMETER} Statements
8789 @cindex PARAMETER statement
8790 @cindex statements, PARAMETER
8792 @command{g77} doesn't allow intrinsics in @code{PARAMETER} statements.
8794 Related to this, @command{g77} doesn't allow non-integral
8795 exponentiation in @code{PARAMETER} statements, such as
8796 @samp{PARAMETER (R=2**.25)}.
8797 It is unlikely @command{g77} will ever support this feature,
8798 as doing it properly requires complete emulation of
8799 a target computer's floating-point facilities when
8800 building @command{g77} as a cross-compiler.
8801 But, if the @command{gcc} back end is enhanced to provide
8802 such a facility, @command{g77} will likely use that facility
8803 in implementing this feature soon afterwards.
8805 @node Arbitrary Concatenation
8806 @subsection Arbitrary Concatenation
8807 @cindex concatenation
8808 @cindex CHARACTER*(*)
8809 @cindex run-time, dynamic allocation
8811 @command{g77} doesn't support arbitrary operands for concatenation
8812 in contexts where run-time allocation is required.
8818 CALL FOO(A // 'suffix')
8821 @node SELECT CASE on CHARACTER Type
8822 @subsection @code{SELECT CASE} on @code{CHARACTER} Type
8824 Character-type selector/cases for @code{SELECT CASE} currently
8827 @node RECURSIVE Keyword
8828 @subsection @code{RECURSIVE} Keyword
8829 @cindex RECURSIVE keyword
8830 @cindex keywords, RECURSIVE
8831 @cindex recursion, lack of
8832 @cindex lack of recursion
8834 @command{g77} doesn't support the @code{RECURSIVE} keyword that
8836 Nor does it provide any means for compiling procedures
8837 designed to do recursion.
8839 All recursive code can be rewritten to not use recursion,
8840 but the result is not pretty.
8842 @node Increasing Precision/Range
8843 @subsection Increasing Precision/Range
8845 @cindex -qrealsize=8
8848 @cindex increasing precision
8849 @cindex precision, increasing
8850 @cindex increasing range
8851 @cindex range, increasing
8855 Some compilers, such as @command{f2c}, have an option (@option{-r8},
8856 @option{-qrealsize=8} or
8857 similar) that provides automatic treatment of @code{REAL}
8858 entities such that they have twice the storage size, and
8859 a corresponding increase in the range and precision, of what
8860 would normally be the @code{REAL(KIND=1)} (default @code{REAL}) type.
8861 (This affects @code{COMPLEX} the same way.)
8863 They also typically offer another option (@option{-i8}) to increase
8864 @code{INTEGER} entities so they are twice as large
8865 (with roughly twice as much range).
8867 (There are potential pitfalls in using these options.)
8869 @command{g77} does not yet offer any option that performs these
8870 kinds of transformations.
8871 Part of the problem is the lack of detailed specifications regarding
8872 exactly how these options affect the interpretation of constants,
8873 intrinsics, and so on.
8875 Until @command{g77} addresses this need, programmers could improve
8876 the portability of their code by modifying it to not require
8877 compile-time options to produce correct results.
8878 Some free tools are available which may help, specifically
8879 in Toolpack (which one would expect to be sound) and the @file{fortran}
8880 section of the Netlib repository.
8882 Use of preprocessors can provide a fairly portable means
8883 to work around the lack of widely portable methods in the Fortran
8884 language itself (though increasing acceptance of Fortran 90 would
8885 alleviate this problem).
8887 @node Popular Non-standard Types
8888 @subsection Popular Non-standard Types
8889 @cindex @code{INTEGER*2} support
8890 @cindex types, @code{INTEGER*2}
8891 @cindex @code{LOGICAL*1} support
8892 @cindex types, @code{LOGICAL*1}
8894 @command{g77} doesn't fully support @code{INTEGER*2}, @code{LOGICAL*1},
8896 In the meantime, version 0.5.18 provides rudimentary support
8899 @node Full Support for Compiler Types
8900 @subsection Full Support for Compiler Types
8902 @cindex @code{REAL*16} support
8903 @cindex types, @code{REAL*16}
8904 @cindex @code{INTEGER*8} support
8905 @cindex types, @code{INTEGER*8}
8906 @command{g77} doesn't support @code{INTEGER}, @code{REAL}, and @code{COMPLEX} equivalents
8907 for @emph{all} applicable back-end-supported types (@code{char}, @code{short int},
8908 @code{int}, @code{long int}, @code{long long int}, and @code{long double}).
8909 This means providing intrinsic support, and maybe constant
8910 support (using F90 syntax) as well, and, for most
8911 machines will result in automatic support of @code{INTEGER*1},
8912 @code{INTEGER*2}, @code{INTEGER*8}, maybe even @code{REAL*16},
8915 @node Array Bounds Expressions
8916 @subsection Array Bounds Expressions
8917 @cindex array elements, in adjustable array bounds
8918 @cindex function references, in adjustable array bounds
8919 @cindex array bounds, adjustable
8920 @cindex @code{DIMENSION} statement
8921 @cindex statements, @code{DIMENSION}
8923 @command{g77} doesn't support more general expressions to dimension
8924 arrays, such as array element references, function
8927 For example, @command{g77} currently does not accept the following:
8931 INTEGER N(10), M(N(2), N(1))
8934 @node POINTER Statements
8935 @subsection POINTER Statements
8936 @cindex POINTER statement
8937 @cindex statements, POINTER
8938 @cindex Cray pointers
8940 @command{g77} doesn't support pointers or allocatable objects
8941 (other than automatic arrays).
8942 This set of features is
8943 probably considered just behind intrinsics
8944 in @code{PARAMETER} statements on the list of large,
8945 important things to add to @command{g77}.
8947 In the meantime, consider using the @code{INTEGER(KIND=7)}
8948 declaration to specify that a variable must be
8949 able to hold a pointer.
8950 This construct is not portable to other non-GNU compilers,
8951 but it is portable to all machines GNU Fortran supports
8952 when @command{g77} is used.
8954 @xref{Functions and Subroutines}, for information on
8955 @code{%VAL()}, @code{%REF()}, and @code{%DESCR()}
8956 constructs, which are useful for passing pointers to
8957 procedures written in languages other than Fortran.
8959 @node Sensible Non-standard Constructs
8960 @subsection Sensible Non-standard Constructs
8962 @command{g77} rejects things other compilers accept,
8963 like @samp{INTRINSIC SQRT,SQRT}.
8964 As time permits in the future, some of these things that are easy for
8965 humans to read and write and unlikely to be intended to mean something
8966 else will be accepted by @command{g77} (though @option{-fpedantic} should
8967 trigger warnings about such non-standard constructs).
8969 Until @command{g77} no longer gratuitously rejects sensible code,
8970 you might as well fix your code
8971 to be more standard-conforming and portable.
8973 The kind of case that is important to except from the
8974 recommendation to change your code is one where following
8975 good coding rules would force you to write non-standard
8976 code that nevertheless has a clear meaning.
8978 For example, when writing an @code{INCLUDE} file that
8979 defines a common block, it might be appropriate to
8980 include a @code{SAVE} statement for the common block
8981 (such as @samp{SAVE /CBLOCK/}), so that variables
8982 defined in the common block retain their values even
8983 when all procedures declaring the common block become
8984 inactive (return to their callers).
8986 However, putting @code{SAVE} statements in an @code{INCLUDE}
8987 file would prevent otherwise standard-conforming code
8988 from also specifying the @code{SAVE} statement, by itself,
8989 to indicate that all local variables and arrays are to
8990 have the @code{SAVE} attribute.
8992 For this reason, @command{g77} already has been changed to
8993 allow this combination, because although the general
8994 problem of gratuitously rejecting unambiguous and
8995 ``safe'' constructs still exists in @command{g77}, this
8996 particular construct was deemed useful enough that
8997 it was worth fixing @command{g77} for just this case.
8999 So, while there is no need to change your code
9000 to avoid using this particular construct, there
9001 might be other, equally appropriate but non-standard
9002 constructs, that you shouldn't have to stop using
9003 just because @command{g77} (or any other compiler)
9004 gratuitously rejects it.
9006 Until the general problem is solved, if you have
9007 any such construct you believe is worthwhile
9008 using (e.g. not just an arbitrary, redundant
9009 specification of an attribute), please submit a
9010 bug report with an explanation, so we can consider
9011 fixing @command{g77} just for cases like yours.
9013 @node READONLY Keyword
9014 @subsection @code{READONLY} Keyword
9017 Support for @code{READONLY}, in @code{OPEN} statements,
9018 requires @code{libg2c} support,
9019 to make sure that @samp{CLOSE(@dots{},STATUS='DELETE')}
9020 does not delete a file opened on a unit
9021 with the @code{READONLY} keyword,
9022 and perhaps to trigger a fatal diagnostic
9023 if a @code{WRITE} or @code{PRINT}
9024 to such a unit is attempted.
9026 @emph{Note:} It is not sufficient for @command{g77} and @code{libg2c}
9027 (its version of @code{libf2c})
9028 to assume that @code{READONLY} does not need some kind of explicit support
9030 due to UNIX systems not (generally) needing it.
9031 @command{g77} is not just a UNIX-based compiler!
9033 Further, mounting of non-UNIX filesystems on UNIX systems
9035 might require proper @code{READONLY} support.
9038 (Similar issues might be involved with supporting the @code{SHARED}
9041 @node FLUSH Statement
9042 @subsection @code{FLUSH} Statement
9044 @command{g77} could perhaps use a @code{FLUSH} statement that
9045 does what @samp{CALL FLUSH} does,
9046 but that supports @samp{*} as the unit designator (same unit as for
9047 @code{PRINT}) and accepts @code{ERR=} and/or @code{IOSTAT=}
9050 @node Expressions in FORMAT Statements
9051 @subsection Expressions in @code{FORMAT} Statements
9052 @cindex FORMAT statement
9053 @cindex statements, FORMAT
9055 @command{g77} doesn't support @samp{FORMAT(I<J>)} and the like.
9056 Supporting this requires a significant redesign or replacement
9059 However, @command{g77} does support
9060 this construct when the expression is constant
9061 (as of version 0.5.22).
9065 PARAMETER (IWIDTH = 12)
9066 10 FORMAT (I<IWIDTH>)
9069 Otherwise, at least for output (@code{PRINT} and
9070 @code{WRITE}), Fortran code making use of this feature can
9071 be rewritten to avoid it by constructing the @code{FORMAT}
9072 string in a @code{CHARACTER} variable or array, then
9073 using that variable or array in place of the @code{FORMAT}
9074 statement label to do the original @code{PRINT} or @code{WRITE}.
9076 Many uses of this feature on input can be rewritten this way
9077 as well, but not all can.
9078 For example, this can be rewritten:
9085 However, this cannot, in general, be rewritten, especially
9086 when @code{ERR=} and @code{END=} constructs are employed:
9093 @node Explicit Assembler Code
9094 @subsection Explicit Assembler Code
9096 @command{g77} needs to provide some way, a la @command{gcc}, for @command{g77}
9097 code to specify explicit assembler code.
9099 @node Q Edit Descriptor
9100 @subsection Q Edit Descriptor
9101 @cindex FORMAT statement
9102 @cindex Q edit descriptor
9103 @cindex edit descriptor, Q
9105 The @code{Q} edit descriptor in @code{FORMAT}s isn't supported.
9106 (This is meant to get the number of characters remaining in an input record.)
9107 Supporting this requires a significant redesign or replacement
9110 A workaround might be using internal I/O or the stream-based intrinsics.
9111 @xref{FGetC Intrinsic (subroutine)}.
9113 @node Old-style PARAMETER Statements
9114 @subsection Old-style PARAMETER Statements
9115 @cindex PARAMETER statement
9116 @cindex statements, PARAMETER
9118 @command{g77} doesn't accept @samp{PARAMETER I=1}.
9119 Supporting this obsolete form of
9120 the @code{PARAMETER} statement would not be particularly hard, as most of the
9121 parsing code is already in place and working.
9124 spent implementing it, you might as well fix your code to use the
9125 standard form, @samp{PARAMETER (I=1)} (possibly needing
9126 @samp{INTEGER I} preceding the @code{PARAMETER} statement as well,
9127 otherwise, in the obsolete form of @code{PARAMETER}, the
9128 type of the variable is set from the type of the constant being
9131 @node TYPE and ACCEPT I/O Statements
9132 @subsection @code{TYPE} and @code{ACCEPT} I/O Statements
9133 @cindex TYPE statement
9134 @cindex statements, TYPE
9135 @cindex ACCEPT statement
9136 @cindex statements, ACCEPT
9138 @command{g77} doesn't support the I/O statements @code{TYPE} and
9140 These are common extensions that should be easy to support,
9141 but also are fairly easy to work around in user code.
9143 Generally, any @samp{TYPE fmt,list} I/O statement can be replaced
9144 by @samp{PRINT fmt,list}.
9145 And, any @samp{ACCEPT fmt,list} statement can be
9146 replaced by @samp{READ fmt,list}.
9148 @node STRUCTURE UNION RECORD MAP
9149 @subsection @code{STRUCTURE}, @code{UNION}, @code{RECORD}, @code{MAP}
9150 @cindex STRUCTURE statement
9151 @cindex statements, STRUCTURE
9152 @cindex UNION statement
9153 @cindex statements, UNION
9154 @cindex RECORD statement
9155 @cindex statements, RECORD
9156 @cindex MAP statement
9157 @cindex statements, MAP
9159 @command{g77} doesn't support @code{STRUCTURE}, @code{UNION}, @code{RECORD},
9161 This set of extensions is quite a bit
9162 lower on the list of large, important things to add to @command{g77}, partly
9163 because it requires a great deal of work either upgrading or
9164 replacing @code{libg2c}.
9166 @node OPEN CLOSE and INQUIRE Keywords
9167 @subsection @code{OPEN}, @code{CLOSE}, and @code{INQUIRE} Keywords
9168 @cindex disposition of files
9169 @cindex OPEN statement
9170 @cindex statements, OPEN
9171 @cindex CLOSE statement
9172 @cindex statements, CLOSE
9173 @cindex INQUIRE statement
9174 @cindex statements, INQUIRE
9176 @command{g77} doesn't have support for keywords such as @code{DISP='DELETE'} in
9177 the @code{OPEN}, @code{CLOSE}, and @code{INQUIRE} statements.
9178 These extensions are easy to add to @command{g77} itself, but
9179 require much more work on @code{libg2c}.
9181 @cindex FORM='PRINT'
9182 @cindex ANS carriage control
9183 @cindex carriage control
9186 @command{g77} doesn't support @code{FORM='PRINT'} or an equivalent to
9187 translate the traditional `carriage control' characters in column 1 of
9188 output to use backspaces, carriage returns and the like. However
9189 programs exist to translate them in output files (or standard output).
9190 These are typically called either @command{fpr} or @command{asa}. You can get
9191 a version of @command{asa} from
9192 @uref{ftp://sunsite.unc.edu/pub/Linux/devel/lang/fortran} for GNU
9193 systems which will probably build easily on other systems.
9194 Alternatively, @command{fpr} is in BSD distributions in various archive
9197 @c (Can both programs can be used in a pipeline,
9198 @c with a named input file,
9199 @c and/or with a named output file???)
9201 @node ENCODE and DECODE
9202 @subsection @code{ENCODE} and @code{DECODE}
9203 @cindex ENCODE statement
9204 @cindex statements, ENCODE
9205 @cindex DECODE statement
9206 @cindex statements, DECODE
9208 @command{g77} doesn't support @code{ENCODE} or @code{DECODE}.
9210 These statements are best replaced by READ and WRITE statements
9211 involving internal files (CHARACTER variables and arrays).
9213 For example, replace a code fragment like
9218 DECODE (80, 9000, LINE) A, B, C
9220 9000 FORMAT (1X, 3(F10.5))
9229 READ (UNIT=LINE, FMT=9000) A, B, C
9231 9000 FORMAT (1X, 3(F10.5))
9234 Similarly, replace a code fragment like
9239 ENCODE (80, 9000, LINE) A, B, C
9241 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
9250 WRITE (UNIT=LINE, FMT=9000) A, B, C
9252 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
9255 It is entirely possible that @code{ENCODE} and @code{DECODE} will
9256 be supported by a future version of @command{g77}.
9258 @node AUTOMATIC Statement
9259 @subsection @code{AUTOMATIC} Statement
9260 @cindex @code{AUTOMATIC} statement
9261 @cindex statements, @code{AUTOMATIC}
9262 @cindex automatic variables
9263 @cindex variables, automatic
9265 @command{g77} doesn't support the @code{AUTOMATIC} statement that
9268 @code{AUTOMATIC} would identify a variable or array
9269 as not being @code{SAVE}'d, which is normally the default,
9270 but which would be especially useful for code that, @emph{generally},
9271 needed to be compiled with the @option{-fno-automatic} option.
9273 @code{AUTOMATIC} also would serve as a hint to the compiler that placing
9274 the variable or array---even a very large array--on the stack is acceptable.
9276 @code{AUTOMATIC} would not, by itself, designate the containing procedure
9279 @code{AUTOMATIC} should work syntactically like @code{SAVE},
9280 in that @code{AUTOMATIC} with no variables listed should apply to
9281 all pertinent variables and arrays
9282 (which would not include common blocks or their members).
9284 Variables and arrays denoted as @code{AUTOMATIC}
9285 would not be permitted to be initialized via @code{DATA}
9286 or other specification of any initial values,
9287 requiring explicit initialization,
9288 such as via assignment statements.
9292 Perhaps @code{UNSAVE} and @code{STATIC},
9293 as strict semantic opposites to @code{SAVE} and @code{AUTOMATIC},
9294 should be provided as well.
9296 @node Suppressing Space Padding
9297 @subsection Suppressing Space Padding of Source Lines
9299 @command{g77} should offer VXT-Fortran-style suppression of virtual
9300 spaces at the end of a source line
9301 if an appropriate command-line option is specified.
9303 This affects cases where
9304 a character constant is continued onto the next line in a fixed-form
9305 source file, as in the following example:
9308 10 PRINT *,'HOW MANY
9313 @command{g77}, and many other compilers, virtually extend
9314 the continued line through column 72 with spaces that become part
9315 of the character constant, but Digital Fortran normally didn't,
9316 leaving only one space between @samp{MANY} and @samp{SPACES?}
9317 in the output of the above statement.
9319 Fairly recently, at least one version of Digital Fortran
9320 was enhanced to provide the other behavior when a
9321 command-line option is specified, apparently due to demand
9322 from readers of the USENET group @file{comp.lang.fortran}
9323 to offer conformance to this widespread practice in the
9325 @command{g77} should return the favor by offering conformance
9326 to Digital's approach to handling the above example.
9328 @node Fortran Preprocessor
9329 @subsection Fortran Preprocessor
9331 @command{g77} should offer a preprocessor designed specifically
9332 for Fortran to replace @samp{cpp -traditional}.
9333 There are several out there worth evaluating, at least.
9335 Such a preprocessor would recognize Hollerith constants,
9336 properly parse comments and character constants, and so on.
9337 It might also recognize, process, and thus preprocess
9338 files included via the @code{INCLUDE} directive.
9340 @node Bit Operations on Floating-point Data
9341 @subsection Bit Operations on Floating-point Data
9342 @cindex @code{And} intrinsic
9343 @cindex intrinsics, @code{And}
9344 @cindex @code{Or} intrinsic
9345 @cindex intrinsics, @code{Or}
9346 @cindex @code{Shift} intrinsic
9347 @cindex intrinsics, @code{Shift}
9349 @command{g77} does not allow @code{REAL} and other non-integral types for
9350 arguments to intrinsics like @code{And}, @code{Or}, and @code{Shift}.
9352 For example, this program is rejected by @command{g77}, because
9353 the intrinsic @code{Iand} does not accept @code{REAL} arguments:
9356 DATA A/7.54/, B/9.112/
9361 @node Really Ugly Character Assignments
9362 @subsection Really Ugly Character Assignments
9364 An option such as @option{-fugly-char} should be provided
9369 DATA A1 / '12345678' /
9379 @node POSIX Standard
9380 @subsection @code{POSIX} Standard
9382 @command{g77} should support the POSIX standard for Fortran.
9384 @node Floating-point Exception Handling
9385 @subsection Floating-point Exception Handling
9386 @cindex floating-point, exceptions
9387 @cindex exceptions, floating-point
9388 @cindex FPE handling
9391 The @command{gcc} backend and, consequently, @command{g77}, currently provides no
9392 general control over whether or not floating-point exceptions are trapped or
9394 (Ignoring them typically results in NaN values being
9395 propagated in systems that conform to IEEE 754.)
9396 The behavior is normally inherited from the system-dependent startup
9397 code, though some targets, such as the Alpha, have code generation
9398 options which change the behavior.
9400 Most systems provide some C-callable mechanism to change this; this can
9401 be invoked at startup using @command{gcc}'s @code{constructor} attribute.
9402 For example, just compiling and linking the following C code with your
9403 program will turn on exception trapping for the ``common'' exceptions
9404 on a GNU system using glibc 2.2 or newer:
9407 #define _GNU_SOURCE 1
9409 static void __attribute__ ((constructor))
9412 /* Enable some exceptions. At startup all exceptions are masked. */
9414 feenableexcept (FE_INVALID|FE_DIVBYZERO|FE_OVERFLOW);
9418 A convenient trick is to compile this something like:
9420 gcc -o libtrapfpe.a trapfpe.c
9422 and then use it by adding @option{-trapfpe} to the @command{g77} command line
9425 @node Nonportable Conversions
9426 @subsection Nonportable Conversions
9427 @cindex nonportable conversions
9428 @cindex conversions, nonportable
9430 @command{g77} doesn't accept some particularly nonportable,
9431 silent data-type conversions such as @code{LOGICAL}
9432 to @code{REAL} (as in @samp{A=.FALSE.}, where @samp{A}
9433 is type @code{REAL}), that other compilers might
9436 Some of these conversions are accepted by @command{g77}
9437 when the @option{-fugly-logint} option is specified.
9438 Perhaps it should accept more or all of them.
9440 @node Large Automatic Arrays
9441 @subsection Large Automatic Arrays
9442 @cindex automatic arrays
9443 @cindex arrays, automatic
9445 Currently, automatic arrays always are allocated on the stack.
9446 For situations where the stack cannot be made large enough,
9447 @command{g77} should offer a compiler option that specifies
9448 allocation of automatic arrays in heap storage.
9450 @node Support for Threads
9451 @subsection Support for Threads
9453 @cindex parallel processing
9455 Neither the code produced by @command{g77} nor the @code{libg2c} library
9456 are thread-safe, nor does @command{g77} have support for parallel processing
9457 (other than the instruction-level parallelism available on some
9459 A package such as PVM might help here.
9461 @node Enabling Debug Lines
9462 @subsection Enabling Debug Lines
9464 @cindex comment line, debug
9466 An option such as @option{-fdebug-lines} should be provided
9467 to turn fixed-form lines beginning with @samp{D}
9468 to be treated as if they began with a space,
9469 instead of as if they began with a @samp{C}
9472 @node Better Warnings
9473 @subsection Better Warnings
9475 Because of how @command{g77} generates code via the back end,
9476 it doesn't always provide warnings the user wants.
9485 Currently, the above is not flagged as a case of
9486 using an uninitialized variable,
9487 because @command{g77} generates a run-time library call that looks,
9488 to the GBE, like it might actually @emph{modify} @samp{A} at run time.
9489 (And, in fact, depending on the previous run-time library call,
9492 Fixing this requires one of the following:
9496 Switch to new library, @code{libg77}, that provides
9497 a more ``clean'' interface,
9498 vis-a-vis input, output, and modified arguments,
9499 so the GBE can tell what's going on.
9501 This would provide a pretty big performance improvement,
9502 at least theoretically, and, ultimately, in practice,
9503 for some types of code.
9506 Have @command{g77} pass a pointer to a temporary
9507 containing a copy of @samp{A},
9508 instead of to @samp{A} itself.
9509 The GBE would then complain about the copy operation
9510 involving a potentially uninitialized variable.
9512 This might also provide a performance boost for some code,
9513 because @samp{A} might then end up living in a register,
9514 which could help with inner loops.
9517 Have @command{g77} use a GBE construct similar to @code{ADDR_EXPR}
9518 but with extra information on the fact that the
9519 item pointed to won't be modified
9520 (a la @code{const} in C).
9522 Probably the best solution for now, but not quite trivial
9523 to implement in the general case.
9526 @node Gracefully Handle Sensible Bad Code
9527 @subsection Gracefully Handle Sensible Bad Code
9529 @command{g77} generally should continue processing for
9530 warnings and recoverable (user) errors whenever possible---that
9531 is, it shouldn't gratuitously make bad or useless code.
9542 When compiling the above with @option{-ff2c-intrinsics-disable},
9543 @command{g77} should indeed complain about passing @code{ZABS},
9544 but it still should compile, instead of rejecting
9545 the entire @code{CALL} statement.
9546 (Some of this is related to improving
9547 the compiler internals to improve how statements are analyzed.)
9549 @node Non-standard Conversions
9550 @subsection Non-standard Conversions
9552 @option{-Wconversion} and related should flag places where non-standard
9553 conversions are found.
9554 Perhaps much of this would be part of @option{-Wugly*}.
9556 @node Non-standard Intrinsics
9557 @subsection Non-standard Intrinsics
9559 @command{g77} needs a new option, like @option{-Wintrinsics}, to warn about use of
9560 non-standard intrinsics without explicit @code{INTRINSIC} statements for them.
9561 This would help find code that might fail silently when ported to another
9564 @node Modifying DO Variable
9565 @subsection Modifying @code{DO} Variable
9567 @command{g77} should warn about modifying @code{DO} variables
9568 via @code{EQUIVALENCE}.
9569 (The internal information gathered to produce this warning
9570 might also be useful in setting the
9571 internal ``doiter'' flag for a variable or even array
9572 reference within a loop, since that might produce faster code someday.)
9574 For example, this code is invalid, so @command{g77} should warn about
9575 the invalid assignment to @samp{NOTHER}:
9578 EQUIVALENCE (I, NOTHER)
9580 IF (I.EQ. 10) NOTHER = 20
9584 @node Better Pedantic Compilation
9585 @subsection Better Pedantic Compilation
9587 @command{g77} needs to support @option{-fpedantic} more thoroughly,
9588 and use it only to generate
9589 warnings instead of rejecting constructs outright.
9591 if a variable that dimensions an array is not a dummy or placed
9592 explicitly in @code{COMMON} (F77 does not allow it to be
9593 placed in @code{COMMON} via @code{EQUIVALENCE}); if specification statements
9594 follow statement-function-definition statements; about all sorts of
9595 syntactic extensions.
9597 @node Warn About Implicit Conversions
9598 @subsection Warn About Implicit Conversions
9600 @command{g77} needs a @option{-Wpromotions} option to warn if source code appears
9601 to expect automatic, silent, and
9602 somewhat dangerous compiler-assisted conversion of @code{REAL(KIND=1)}
9603 constants to @code{REAL(KIND=2)} based on context.
9605 For example, it would warn about cases like this:
9608 DOUBLE PRECISION FOO
9609 PARAMETER (TZPHI = 9.435784839284958)
9613 @node Invalid Use of Hollerith Constant
9614 @subsection Invalid Use of Hollerith Constant
9616 @command{g77} should disallow statements like @samp{RETURN 2HAB},
9617 which are invalid in both source forms
9618 (unlike @samp{RETURN (2HAB)},
9619 which probably still makes no sense but at least can
9620 be reliably parsed).
9621 Fixed-form processing rejects it, but not free-form, except
9622 in a way that is a bit difficult to understand.
9624 @node Dummy Array Without Dimensioning Dummy
9625 @subsection Dummy Array Without Dimensioning Dummy
9627 @command{g77} should complain when a list of dummy arguments containing an
9628 adjustable dummy array does
9629 not also contain every variable listed in the dimension list of the
9632 Currently, @command{g77} does complain about a variable that
9633 dimensions an array but doesn't appear in any dummy list or @code{COMMON}
9634 area, but this needs to be extended to catch cases where it doesn't appear in
9635 every dummy list that also lists any arrays it dimensions.
9637 For example, @command{g77} should warn about the entry point @samp{ALT}
9638 below, since it includes @samp{ARRAY} but not @samp{ISIZE} in its
9642 SUBROUTINE PRIMARY(ARRAY, ISIZE)
9647 @node Invalid FORMAT Specifiers
9648 @subsection Invalid FORMAT Specifiers
9650 @command{g77} should check @code{FORMAT} specifiers for validity
9651 as it does @code{FORMAT} statements.
9653 For example, a diagnostic would be produced for:
9656 PRINT 'HI THERE!' !User meant PRINT *, 'HI THERE!'
9659 @node Ambiguous Dialects
9660 @subsection Ambiguous Dialects
9662 @command{g77} needs a set of options such as @option{-Wugly*}, @option{-Wautomatic},
9663 @option{-Wvxt}, @option{-Wf90}, and so on.
9664 These would warn about places in the user's source where ambiguities
9665 are found, helpful in resolving ambiguities in the program's
9666 dialect or dialects.
9669 @subsection Unused Labels
9671 @command{g77} should warn about unused labels when @option{-Wunused} is in effect.
9673 @node Informational Messages
9674 @subsection Informational Messages
9676 @command{g77} needs an option to suppress information messages (notes).
9677 @option{-w} does this but also suppresses warnings.
9678 The default should be to suppress info messages.
9680 Perhaps info messages should simply be eliminated.
9682 @node Uninitialized Variables at Run Time
9683 @subsection Uninitialized Variables at Run Time
9685 @command{g77} needs an option to initialize everything (not otherwise
9686 explicitly initialized) to ``weird''
9687 (machine-dependent) values, e.g. NaNs, bad (non-@code{NULL}) pointers, and
9688 largest-magnitude integers, would help track down references to
9689 some kinds of uninitialized variables at run time.
9691 Note that use of the options @samp{-O -Wuninitialized} can catch
9692 many such bugs at compile time.
9694 @node Portable Unformatted Files
9695 @subsection Portable Unformatted Files
9697 @cindex unformatted files
9698 @cindex file formats
9700 @cindex byte ordering
9701 @command{g77} has no facility for exchanging unformatted files with systems
9702 using different number formats---even differing only in endianness (byte
9703 order)---or written by other compilers. Some compilers provide
9704 facilities at least for doing byte-swapping during unformatted I/O.
9706 It is unrealistic to expect to cope with exchanging unformatted files
9707 with arbitrary other compiler runtimes, but the @command{g77} runtime
9708 should at least be able to read files written by @command{g77} on systems
9709 with different number formats, particularly if they differ only in byte
9712 In case you do need to write a program to translate to or from
9713 @command{g77} (@code{libf2c}) unformatted files, they are written as
9717 Unformatted sequential records consist of
9720 A number giving the length of the record contents;
9722 the length of record contents again (for backspace).
9725 The record length is of C type
9726 @code{long}; this means that it is 8 bytes on 64-bit systems such as
9727 Alpha GNU/Linux and 4 bytes on other systems, such as x86 GNU/Linux.
9728 Consequently such files cannot be exchanged between 64-bit and 32-bit
9729 systems, even with the same basic number format.
9731 Unformatted direct access files form a byte stream of length
9732 @var{records}*@var{recl} bytes, where @var{records} is the maximum
9733 record number (@code{REC=@var{records}}) written and @var{recl} is the
9734 record length in bytes specified in the @code{OPEN} statement
9735 (@code{RECL=@var{recl}}). Data appear in the records as determined by
9736 the relevant @code{WRITE} statement. Dummy records with arbitrary
9737 contents appear in the file in place of records which haven't been
9741 Thus for exchanging a sequential or direct access unformatted file
9742 between big- and little-endian 32-bit systems using IEEE 754 floating
9743 point it would be sufficient to reverse the bytes in consecutive words
9744 in the file if, and @emph{only} if, only @code{REAL*4}, @code{COMPLEX},
9745 @code{INTEGER*4} and/or @code{LOGICAL*4} data have been written to it by
9748 If necessary, it is possible to do byte-oriented i/o with @command{g77}'s
9749 @code{FGETC} and @code{FPUTC} intrinsics. Byte-swapping can be done in
9750 Fortran by equivalencing larger sized variables to an @code{INTEGER*1}
9751 array or a set of scalars.
9755 If you need to exchange binary data between arbitrary system and
9756 compiler variations, we recommend using a portable binary format with
9757 Fortran bindings, such as NCSA's HDF (@uref{http://hdf.ncsa.uiuc.edu/})
9758 or PACT's PDB@footnote{No, not @emph{that} one.}
9759 (@uref{http://www.llnl.gov/def_sci/pact/pact_homepage.html}). (Unlike,
9760 say, CDF or XDR, HDF-like systems write in the native number formats and
9761 only incur overhead when they are read on a system with a different
9762 format.) A future @command{g77} runtime library should use such
9765 @node Better List-directed I/O
9766 @subsection Better List-directed I/O
9768 Values output using list-directed I/O
9769 (@samp{PRINT *, R, D})
9770 should be written with a field width, precision, and so on
9771 appropriate for the type (precision) of each value.
9773 (Currently, no distinction is made between single-precision
9774 and double-precision values
9777 It is likely this item will require the @code{libg77} project
9780 In the meantime, use of formatted I/O is recommended.
9781 While it might be of little consolation,
9782 @command{g77} does support @samp{FORMAT(F<WIDTH>.4)}, for example,
9783 as long as @samp{WIDTH} is defined as a named constant
9784 (via @code{PARAMETER}).
9785 That at least allows some compile-time specification
9786 of the precision of a data type,
9787 perhaps controlled by preprocessing directives.
9789 @node Default to Console I/O
9790 @subsection Default to Console I/O
9792 The default I/O units,
9793 specified by @samp{READ @var{fmt}},
9794 @samp{READ (UNIT=*)},
9795 @samp{WRITE (UNIT=*)}, and
9796 @samp{PRINT @var{fmt}},
9797 should not be units 5 (input) and 6 (output),
9798 but, rather, unit numbers not normally available
9799 for use in statements such as @code{OPEN} and @code{CLOSE}.
9801 Changing this would allow a program to connect units 5 and 6
9802 to files via @code{OPEN},
9803 but still use @samp{READ (UNIT=*)} and @samp{PRINT}
9804 to do I/O to the ``console''.
9806 This change probably requires the @code{libg77} project.
9808 @node Labels Visible to Debugger
9809 @subsection Labels Visible to Debugger
9811 @command{g77} should output debugging information for statements labels,
9812 for use by debuggers that know how to support them.
9813 Same with weirder things like construct names.
9814 It is not yet known if any debug formats or debuggers support these.
9816 @node Disappointments
9817 @section Disappointments and Misunderstandings
9819 These problems are perhaps regrettable, but we don't know any practical
9820 way around them for now.
9823 * Mangling of Names:: @samp{SUBROUTINE FOO} is given
9824 external name @samp{foo_}.
9825 * Multiple Definitions of External Names:: No doing both @samp{COMMON /FOO/}
9826 and @samp{SUBROUTINE FOO}.
9827 * Limitation on Implicit Declarations:: No @samp{IMPLICIT CHARACTER*(*)}.
9830 @node Mangling of Names
9831 @subsection Mangling of Names in Source Code
9832 @cindex naming issues
9833 @cindex external names
9834 @cindex common blocks
9838 The current external-interface design, which includes naming of
9839 external procedures, COMMON blocks, and the library interface,
9840 has various usability problems, including things like adding
9841 underscores where not really necessary (and preventing easier
9842 inter-language operability) and yet not providing complete
9843 namespace freedom for user C code linked with Fortran apps (due
9844 to the naming of functions in the library, among other things).
9846 Project GNU should at least get all this ``right'' for systems
9847 it fully controls, such as the Hurd, and provide defaults and
9848 options for compatibility with existing systems and interoperability
9849 with popular existing compilers.
9851 @node Multiple Definitions of External Names
9852 @subsection Multiple Definitions of External Names
9854 @cindex BLOCK DATA statement
9855 @cindex statements, BLOCK DATA
9856 @cindex @code{COMMON} statement
9857 @cindex statements, @code{COMMON}
9858 @cindex naming conflicts
9860 @command{g77} doesn't allow a common block and an external procedure or
9861 @code{BLOCK DATA} to have the same name.
9862 Some systems allow this, but @command{g77} does not,
9863 to be compatible with @command{f2c}.
9865 @command{g77} could special-case the way it handles
9866 @code{BLOCK DATA}, since it is not compatible with @command{f2c} in this
9867 particular area (necessarily, since @command{g77} offers an
9868 important feature here), but
9869 it is likely that such special-casing would be very annoying to people
9870 with programs that use @samp{EXTERNAL FOO}, with no other mention of
9871 @samp{FOO} in the same program unit, to refer to external procedures, since
9872 the result would be that @command{g77} would treat these references as requests to
9873 force-load BLOCK DATA program units.
9875 In that case, if @command{g77} modified
9876 names of @code{BLOCK DATA} so they could have the same names as
9877 @code{COMMON}, users
9878 would find that their programs wouldn't link because the @samp{FOO} procedure
9879 didn't have its name translated the same way.
9882 @command{g77} could emit a null-but-externally-satisfying definition of
9883 @samp{FOO} with its name transformed as if it had been a
9884 @code{BLOCK DATA}, but that probably invites more trouble than it's
9887 @node Limitation on Implicit Declarations
9888 @subsection Limitation on Implicit Declarations
9889 @cindex IMPLICIT CHARACTER*(*) statement
9890 @cindex statements, IMPLICIT CHARACTER*(*)
9892 @command{g77} disallows @code{IMPLICIT CHARACTER*(*)}.
9893 This is not standard-conforming.
9896 @section Certain Changes We Don't Want to Make
9898 This section lists changes that people frequently request, but which
9899 we do not make because we think GNU Fortran is better without them.
9902 * Backslash in Constants:: Why @samp{'\\'} is a constant that
9903 is one, not two, characters long.
9904 * Initializing Before Specifying:: Why @samp{DATA VAR/1/} can't precede
9906 * Context-Sensitive Intrinsicness:: Why @samp{CALL SQRT} won't work.
9907 * Context-Sensitive Constants:: Why @samp{9.435784839284958} is a
9908 single-precision constant,
9909 and might be interpreted as
9910 @samp{9.435785} or similar.
9911 * Equivalence Versus Equality:: Why @samp{.TRUE. .EQ. .TRUE.} won't work.
9912 * Order of Side Effects:: Why @samp{J = IFUNC() - IFUNC()} might
9913 not behave as expected.
9916 @node Backslash in Constants
9917 @subsection Backslash in Constants
9919 @cindex @command{f77} support
9920 @cindex support, @command{f77}
9922 In the opinion of many experienced Fortran users,
9923 @option{-fno-backslash} should be the default, not @option{-fbackslash},
9924 as currently set by @command{g77}.
9926 First of all, you can always specify
9927 @option{-fno-backslash} to turn off this processing.
9929 Despite not being within the spirit (though apparently within the
9930 letter) of the ANSI FORTRAN 77 standard, @command{g77} defaults to
9931 @option{-fbackslash} because that is what most UNIX @command{f77} commands
9932 default to, and apparently lots of code depends on this feature.
9934 This is a particularly troubling issue.
9935 The use of a C construct in the midst of Fortran code
9936 is bad enough, worse when it makes existing Fortran
9937 programs stop working (as happens when programs written
9938 for non-UNIX systems are ported to UNIX systems with
9939 compilers that provide the @option{-fbackslash} feature
9940 as the default---sometimes with no option to turn it off).
9942 The author of GNU Fortran wished, for reasons of linguistic
9943 purity, to make @option{-fno-backslash} the default for GNU
9944 Fortran and thus require users of UNIX @command{f77} and @command{f2c}
9945 to specify @option{-fbackslash} to get the UNIX behavior.
9947 However, the realization that @command{g77} is intended as
9948 a replacement for @emph{UNIX} @command{f77}, caused the author
9949 to choose to make @command{g77} as compatible with
9950 @command{f77} as feasible, which meant making @option{-fbackslash}
9953 The primary focus on compatibility is at the source-code
9954 level, and the question became ``What will users expect
9955 a replacement for @command{f77} to do, by default?''
9956 Although at least one UNIX @command{f77} does not provide
9957 @option{-fbackslash} as a default, it appears that
9958 the majority of them do, which suggests that
9959 the majority of code that is compiled by UNIX @command{f77}
9960 compilers expects @option{-fbackslash} to be the default.
9962 It is probably the case that more code exists
9963 that would @emph{not} work with @option{-fbackslash}
9964 in force than code that requires it be in force.
9966 However, most of @emph{that} code is not being compiled
9968 and when it is, new build procedures (shell scripts,
9969 makefiles, and so on) must be set up anyway so that
9970 they work under UNIX.
9971 That makes a much more natural and safe opportunity for
9972 non-UNIX users to adapt their build procedures for
9973 @command{g77}'s default of @option{-fbackslash} than would
9974 exist for the majority of UNIX @command{f77} users who
9975 would have to modify existing, working build procedures
9976 to explicitly specify @option{-fbackslash} if that was
9979 One suggestion has been to configure the default for
9980 @option{-fbackslash} (and perhaps other options as well)
9981 based on the configuration of @command{g77}.
9983 This is technically quite straightforward, but will be avoided
9984 even in cases where not configuring defaults to be
9985 dependent on a particular configuration greatly inconveniences
9986 some users of legacy code.
9988 Many users appreciate the GNU compilers because they provide an
9989 environment that is uniform across machines.
9990 These users would be
9991 inconvenienced if the compiler treated things like the
9992 format of the source code differently on certain machines.
9994 Occasionally users write programs intended only for a particular machine
9996 On these occasions, the users would benefit if the GNU Fortran compiler
9997 were to support by default the same dialect as the other compilers on
9999 But such applications are rare.
10000 And users writing a
10001 program to run on more than one type of machine cannot possibly benefit
10002 from this kind of compatibility.
10003 (This is consistent with the design goals for @command{gcc}.
10004 To change them for @command{g77}, you must first change them
10006 Do not ask the maintainers of @command{g77} to do this for you,
10007 or to disassociate @command{g77} from the widely understood, if
10008 not widely agreed-upon, goals for GNU compilers in general.)
10010 This is why GNU Fortran does and will treat backslashes in the same
10011 fashion on all types of machines (by default).
10012 @xref{Direction of Language Development}, for more information on
10013 this overall philosophy guiding the development of the GNU Fortran
10016 Of course, users strongly concerned about portability should indicate
10017 explicitly in their build procedures which options are expected
10018 by their source code, or write source code that has as few such
10019 expectations as possible.
10021 For example, avoid writing code that depends on backslash (@samp{\})
10022 being interpreted either way in particular, such as by
10023 starting a program unit with:
10027 PARAMETER (BACKSL = '\\')
10031 Then, use concatenation of @samp{BACKSL} anyplace a backslash
10033 In this way, users can write programs which have the same meaning
10034 in many Fortran dialects.
10036 (However, this technique does not work for Hollerith constants---which
10037 is just as well, since the only generally portable uses for Hollerith
10038 constants are in places where character constants can and should
10039 be used instead, for readability.)
10041 @node Initializing Before Specifying
10042 @subsection Initializing Before Specifying
10043 @cindex initialization, statement placement
10044 @cindex placing initialization statements
10046 @command{g77} does not allow @samp{DATA VAR/1/} to appear in the
10047 source code before @samp{COMMON VAR},
10048 @samp{DIMENSION VAR(10)}, @samp{INTEGER VAR}, and so on.
10049 In general, @command{g77} requires initialization of a variable
10050 or array to be specified @emph{after} all other specifications
10051 of attributes (type, size, placement, and so on) of that variable
10052 or array are specified (though @emph{confirmation} of data type is
10055 It is @emph{possible} @command{g77} will someday allow all of this,
10056 even though it is not allowed by the FORTRAN 77 standard.
10058 Then again, maybe it is better to have
10059 @command{g77} always require placement of @code{DATA}
10060 so that it can possibly immediately write constants
10061 to the output file, thus saving time and space.
10063 That is, @samp{DATA A/1000000*1/} should perhaps always
10064 be immediately writable to canonical assembler, unless it's already known
10065 to be in a @code{COMMON} area following as-yet-uninitialized stuff,
10066 and to do this it cannot be followed by @samp{COMMON A}.
10068 @node Context-Sensitive Intrinsicness
10069 @subsection Context-Sensitive Intrinsicness
10070 @cindex intrinsics, context-sensitive
10071 @cindex context-sensitive intrinsics
10073 @command{g77} treats procedure references to @emph{possible} intrinsic
10074 names as always enabling their intrinsic nature, regardless of
10075 whether the @emph{form} of the reference is valid for that
10078 For example, @samp{CALL SQRT} is interpreted by @command{g77} as
10079 an invalid reference to the @code{SQRT} intrinsic function,
10080 because the reference is a subroutine invocation.
10082 First, @command{g77} recognizes the statement @samp{CALL SQRT}
10083 as a reference to a @emph{procedure} named @samp{SQRT}, not
10084 to a @emph{variable} with that name (as it would for a statement
10085 such as @samp{V = SQRT}).
10087 Next, @command{g77} establishes that, in the program unit being compiled,
10088 @code{SQRT} is an intrinsic---not a subroutine that
10089 happens to have the same name as an intrinsic (as would be
10090 the case if, for example, @samp{EXTERNAL SQRT} was present).
10092 Finally, @command{g77} recognizes that the @emph{form} of the
10093 reference is invalid for that particular intrinsic.
10094 That is, it recognizes that it is invalid for an intrinsic
10095 @emph{function}, such as @code{SQRT}, to be invoked as
10096 a @emph{subroutine}.
10098 At that point, @command{g77} issues a diagnostic.
10100 Some users claim that it is ``obvious'' that @samp{CALL SQRT}
10101 references an external subroutine of their own, not an
10102 intrinsic function.
10104 However, @command{g77} knows about intrinsic
10105 subroutines, not just functions, and is able to support both having
10106 the same names, for example.
10108 As a result of this, @command{g77} rejects calls
10109 to intrinsics that are not subroutines, and function invocations
10110 of intrinsics that are not functions, just as it (and most compilers)
10111 rejects invocations of intrinsics with the wrong number (or types)
10114 So, use the @samp{EXTERNAL SQRT} statement in a program unit that calls
10115 a user-written subroutine named @samp{SQRT}.
10117 @node Context-Sensitive Constants
10118 @subsection Context-Sensitive Constants
10119 @cindex constants, context-sensitive
10120 @cindex context-sensitive constants
10122 @command{g77} does not use context to determine the types of
10123 constants or named constants (@code{PARAMETER}), except
10124 for (non-standard) typeless constants such as @samp{'123'O}.
10126 For example, consider the following statement:
10129 PRINT *, 9.435784839284958 * 2D0
10133 @command{g77} will interpret the (truncated) constant
10134 @samp{9.435784839284958} as a @code{REAL(KIND=1)}, not @code{REAL(KIND=2)},
10135 constant, because the suffix @code{D0} is not specified.
10137 As a result, the output of the above statement when
10138 compiled by @command{g77} will appear to have ``less precision''
10139 than when compiled by other compilers.
10141 In these and other cases, some compilers detect the
10142 fact that a single-precision constant is used in
10143 a double-precision context and therefore interpret the
10144 single-precision constant as if it was @emph{explicitly}
10145 specified as a double-precision constant.
10146 (This has the effect of appending @emph{decimal}, not
10147 @emph{binary}, zeros to the fractional part of the
10148 number---producing different computational results.)
10150 The reason this misfeature is dangerous is that a slight,
10151 apparently innocuous change to the source code can change
10152 the computational results.
10157 DOUBLE PRECISION FIVE
10158 PARAMETER (ALMOST = 5.000000000001)
10160 CLOSE = 5.000000000001
10161 PRINT *, 5.000000000001 - FIVE
10162 PRINT *, ALMOST - FIVE
10163 PRINT *, CLOSE - FIVE
10168 Running the above program should
10169 result in the same value being
10170 printed three times.
10171 With @command{g77} as the compiler,
10174 However, compiled by many other compilers,
10175 running the above program would print
10176 two or three distinct values, because
10177 in two or three of the statements, the
10178 constant @samp{5.000000000001}, which
10179 on most systems is exactly equal to @samp{5.}
10180 when interpreted as a single-precision constant,
10181 is instead interpreted as a double-precision
10182 constant, preserving the represented
10184 However, this ``clever'' promotion of
10185 type does not extend to variables or,
10186 in some compilers, to named constants.
10188 Since programmers often are encouraged to replace manifest
10189 constants or permanently-assigned variables with named
10190 constants (@code{PARAMETER} in Fortran), and might need
10191 to replace some constants with variables having the same
10192 values for pertinent portions of code,
10193 it is important that compilers treat code so modified in the
10194 same way so that the results of such programs are the same.
10195 @command{g77} helps in this regard by treating constants just
10196 the same as variables in terms of determining their types
10197 in a context-independent way.
10199 Still, there is a lot of existing Fortran code that has
10200 been written to depend on the way other compilers freely
10201 interpret constants' types based on context, so anything
10202 @command{g77} can do to help flag cases of this in such code
10203 could be very helpful.
10205 @node Equivalence Versus Equality
10206 @subsection Equivalence Versus Equality
10207 @cindex .EQV., with integer operands
10208 @cindex comparing logical expressions
10209 @cindex logical expressions, comparing
10211 Use of @code{.EQ.} and @code{.NE.} on @code{LOGICAL} operands
10212 is not supported, except via @option{-fugly-logint}, which is not
10213 recommended except for legacy code (where the behavior expected
10214 by the @emph{code} is assumed).
10216 Legacy code should be changed, as resources permit, to use @code{.EQV.}
10217 and @code{.NEQV.} instead, as these are permitted by the various
10220 New code should never be written expecting @code{.EQ.} or @code{.NE.}
10221 to work if either of its operands is @code{LOGICAL}.
10223 The problem with supporting this ``feature'' is that there is
10224 unlikely to be consensus on how it works, as illustrated by the
10225 following sample program:
10229 DATA L,M,N /3*.FALSE./
10230 IF (L.AND.M.EQ.N) PRINT *,'L.AND.M.EQ.N'
10234 The issue raised by the above sample program is: what is the
10235 precedence of @code{.EQ.} (and @code{.NE.}) when applied to
10236 @code{LOGICAL} operands?
10238 Some programmers will argue that it is the same as the precedence
10239 for @code{.EQ.} when applied to numeric (such as @code{INTEGER})
10241 By this interpretation, the subexpression @samp{M.EQ.N} must be
10242 evaluated first in the above program, resulting in a program that,
10243 when run, does not execute the @code{PRINT} statement.
10245 Other programmers will argue that the precedence is the same as
10246 the precedence for @code{.EQV.}, which is restricted by the standards
10247 to @code{LOGICAL} operands.
10248 By this interpretation, the subexpression @samp{L.AND.M} must be
10249 evaluated first, resulting in a program that @emph{does} execute
10250 the @code{PRINT} statement.
10252 Assigning arbitrary semantic interpretations to syntactic expressions
10253 that might legitimately have more than one ``obvious'' interpretation
10254 is generally unwise.
10256 The creators of the various Fortran standards have done a good job
10257 in this case, requiring a distinct set of operators (which have their
10258 own distinct precedence) to compare @code{LOGICAL} operands.
10259 This requirement results in expression syntax with more certain
10260 precedence (without requiring substantial context), making it easier
10261 for programmers to read existing code.
10262 @command{g77} will avoid muddying up elements of the Fortran language
10263 that were well-designed in the first place.
10265 (Ask C programmers about the precedence of expressions such as
10266 @samp{(a) & (b)} and @samp{(a) - (b)}---they cannot even tell
10267 you, without knowing more context, whether the @samp{&} and @samp{-}
10268 operators are infix (binary) or unary!)
10270 Most dangerous of all is the fact that,
10271 even assuming consensus on its meaning,
10272 an expression like @samp{L.AND.M.EQ.N},
10273 if it is the result of a typographical error,
10274 doesn't @emph{look} like it has such a typo.
10275 Even experienced Fortran programmers would not likely notice that
10276 @samp{L.AND.M.EQV.N} was, in fact, intended.
10278 So, this is a prime example of a circumstance in which
10279 a quality compiler diagnoses the code,
10280 instead of leaving it up to someone debugging it
10281 to know to turn on special compiler options
10282 that might diagnose it.
10284 @node Order of Side Effects
10285 @subsection Order of Side Effects
10286 @cindex side effects, order of evaluation
10287 @cindex order of evaluation, side effects
10289 @command{g77} does not necessarily produce code that, when run, performs
10290 side effects (such as those performed by function invocations)
10291 in the same order as in some other compiler---or even in the same
10292 order as another version, port, or invocation (using different
10293 command-line options) of @command{g77}.
10295 It is never safe to depend on the order of evaluation of side effects.
10296 For example, an expression like this may very well behave differently
10297 from one compiler to another:
10300 J = IFUNC() - IFUNC()
10304 There is no guarantee that @samp{IFUNC} will be evaluated in any particular
10306 Either invocation might happen first.
10307 If @samp{IFUNC} returns 5 the first time it is invoked, and
10308 returns 12 the second time, @samp{J} might end up with the
10309 value @samp{7}, or it might end up with @samp{-7}.
10311 Generally, in Fortran, procedures with side-effects intended to
10312 be visible to the caller are best designed as @emph{subroutines},
10314 Examples of such side-effects include:
10318 The generation of random numbers
10319 that are intended to influence return values.
10323 (other than internal I/O to local variables).
10326 Updating information in common blocks.
10329 An example of a side-effect that is not intended to be visible
10330 to the caller is a function that maintains a cache of recently
10331 calculated results, intended solely to speed repeated invocations
10332 of the function with identical arguments.
10333 Such a function can be safely used in expressions, because
10334 if the compiler optimizes away one or more calls to the
10335 function, operation of the program is unaffected (aside
10336 from being speeded up).
10338 @node Warnings and Errors
10339 @section Warning Messages and Error Messages
10341 @cindex error messages
10342 @cindex warnings vs errors
10343 @cindex messages, warning and error
10344 The GNU compiler can produce two kinds of diagnostics: errors and
10346 Each kind has a different purpose:
10350 @emph{Errors} report problems that make it impossible to compile your
10352 GNU Fortran reports errors with the source file name, line
10353 number, and column within the line where the problem is apparent.
10356 @emph{Warnings} report other unusual conditions in your code that
10357 @emph{might} indicate a problem, although compilation can (and does)
10359 Warning messages also report the source file name, line number,
10360 and column information,
10361 but include the text @samp{warning:} to distinguish them
10362 from error messages.
10365 Warnings might indicate danger points where you should check to make sure
10366 that your program really does what you intend; or the use of obsolete
10367 features; or the use of nonstandard features of GNU Fortran.
10368 Many warnings are issued only if you ask for them, with one of the
10369 @option{-W} options (for instance, @option{-Wall} requests a variety of
10372 @emph{Note:} Currently, the text of the line and a pointer to the column
10373 is printed in most @command{g77} diagnostics.
10375 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
10376 more detail on these and related command-line options.
10378 @node Open Questions
10379 @chapter Open Questions
10381 Please consider offering useful answers to these questions!
10385 @code{LOC()} and other intrinsics are probably somewhat misclassified.
10386 Is the a need for more precise classification of intrinsics, and if so,
10387 what are the appropriate groupings?
10388 Is there a need to individually
10389 enable/disable/delete/hide intrinsics from the command line?
10393 @chapter Reporting Bugs
10395 @cindex reporting bugs
10397 Your bug reports play an essential role in making GNU Fortran reliable.
10399 When you encounter a problem, the first thing to do is to see if it is
10400 already known. @xref{Trouble}. If it isn't known, then you should
10401 report the problem.
10404 * Criteria: Bug Criteria. Have you really found a bug?
10405 * Reporting: Bug Reporting. How to report a bug effectively.
10408 @xref{Trouble,,Known Causes of Trouble with GNU Fortran},
10409 for information on problems we already know about.
10411 @xref{Service,,How To Get Help with GNU Fortran},
10412 for information on where to ask for help.
10415 @section Have You Found a Bug?
10416 @cindex bug criteria
10418 If you are not sure whether you have found a bug, here are some guidelines:
10421 @cindex fatal signal
10424 If the compiler gets a fatal signal, for any input whatever, that is a
10426 Reliable compilers never crash---they just remain obsolete.
10428 @cindex invalid assembly code
10429 @cindex assembly code, invalid
10431 If the compiler produces invalid assembly code, for any input whatever,
10432 @c (except an @code{asm} statement),
10433 that is a compiler bug, unless the
10434 compiler reports errors (not just warnings) which would ordinarily
10435 prevent the assembler from being run.
10437 @cindex undefined behavior
10438 @cindex undefined function value
10440 If the compiler produces valid assembly code that does not correctly
10441 execute the input source code, that is a compiler bug.
10443 However, you must double-check to make sure, because you might have run
10444 into an incompatibility between GNU Fortran and traditional Fortran.
10445 @c (@pxref{Incompatibilities}).
10446 These incompatibilities might be considered
10447 bugs, but they are inescapable consequences of valuable features.
10449 Or you might have a program whose behavior is undefined, which happened
10450 by chance to give the desired results with another Fortran compiler.
10451 It is best to check the relevant Fortran standard thoroughly if
10452 it is possible that the program indeed does something undefined.
10454 After you have localized the error to a single source line, it should
10455 be easy to check for these things.
10456 If your program is correct and well defined, you have found
10459 It might help if, in your submission, you identified the specific
10460 language in the relevant Fortran standard that specifies the
10461 desired behavior, if it isn't likely to be obvious and agreed-upon
10462 by all Fortran users.
10465 If the compiler produces an error message for valid input, that is a
10468 @cindex invalid input
10470 If the compiler does not produce an error message for invalid input,
10471 that is a compiler bug.
10472 However, you should note that your idea of
10473 ``invalid input'' might be someone else's idea
10474 of ``an extension'' or ``support for traditional practice''.
10477 If you are an experienced user of Fortran compilers, your suggestions
10478 for improvement of GNU Fortran are welcome in any case.
10481 Many, perhaps most, bug reports against @command{g77} turn out to
10482 be bugs in the user's code.
10483 While we find such bug reports educational, they sometimes take
10484 a considerable amount of time to track down or at least respond
10485 to---time we could be spending making @command{g77}, not some user's
10488 Some steps you can take to verify that the bug is not certainly
10489 in the code you're compiling with @command{g77}:
10493 Compile your code using the @command{g77} options @samp{-W -Wall -O}.
10494 These options enable many useful warning; the @option{-O} option
10495 enables flow analysis that enables the uninitialized-variable
10498 If you investigate the warnings and find evidence of possible bugs
10499 in your code, fix them first and retry @command{g77}.
10502 Compile your code using the @command{g77} options @option{-finit-local-zero},
10503 @option{-fno-automatic}, @option{-ffloat-store}, and various
10504 combinations thereof.
10506 If your code works with any of these combinations, that is not
10507 proof that the bug isn't in @command{g77}---a @command{g77} bug exposed
10508 by your code might simply be avoided, or have a different, more subtle
10509 effect, when different options are used---but it can be a
10510 strong indicator that your code is making unwarranted assumptions
10511 about the Fortran dialect and/or underlying machine it is
10512 being compiled and run on.
10514 @xref{Overly Convenient Options,,Overly Convenient Command-Line Options},
10515 for information on the @option{-fno-automatic} and
10516 @option{-finit-local-zero} options and how to convert
10517 their use into selective changes in your own code.
10521 Validate your code with @command{ftnchek} or a similar code-checking
10523 @command{ftnchek} can be found at @uref{ftp://ftp.netlib.org/fortran}
10524 or @uref{ftp://ftp.dsm.fordham.edu}.
10527 @cindex Makefile example
10528 Here are some sample @file{Makefile} rules using @command{ftnchek}
10529 ``project'' files to do cross-file checking and @command{sfmakedepend}
10530 (from @uref{ftp://ahab.rutgers.edu/pub/perl/sfmakedepend})
10531 to maintain dependencies automatically.
10532 These assume the use of GNU @command{make}.
10535 # Dummy suffix for ftnchek targets:
10539 # How to compile .f files (for implicit rule):
10541 # Assume `include' directory:
10542 FFLAGS = -Iinclude -g -O -Wall
10544 # Flags for ftnchek:
10545 CHEK1 = -array=0 -include=includes -noarray
10546 CHEK2 = -nonovice -usage=1 -notruncation
10547 CHEKFLAGS = $(CHEK1) $(CHEK2)
10549 # Run ftnchek with all the .prj files except the one corresponding
10550 # to the target's root:
10552 ftnchek $(filter-out $*.prj,$(PRJS)) $(CHEKFLAGS) \
10553 -noextern -library $<
10555 # Derive a project file from a source file:
10557 ftnchek $(CHEKFLAGS) -noextern -project -library $<
10559 # The list of objects is assumed to be in variable OBJS.
10560 # Sources corresponding to the objects:
10561 SRCS = $(OBJS:%.o=%.f)
10562 # ftnchek project files:
10563 PRJS = $(OBJS:%.o=%.prj)
10565 # Build the program
10567 $(FC) -o $@ $(OBJS)
10569 chekall: $(PRJS) ; \
10570 ftnchek $(CHEKFLAGS) $(PRJS)
10574 # For Emacs M-x find-tag:
10578 # Rebuild dependencies:
10580 sfmakedepend -I $(PLTLIBDIR) -I includes -a prj $(SRCS1)
10584 Try your code out using other Fortran compilers, such as @command{f2c}.
10585 If it does not work on at least one other compiler (assuming the
10586 compiler supports the features the code needs), that is a strong
10587 indicator of a bug in the code.
10589 However, even if your code works on many compilers @emph{except}
10590 @command{g77}, that does @emph{not} mean the bug is in @command{g77}.
10591 It might mean the bug is in your code, and that @command{g77} simply
10592 exposes it more readily than other compilers.
10595 @node Bug Reporting
10596 @section How to Report Bugs
10597 @cindex compiler bugs, reporting
10599 Bugs should be reported to our bug database. Please refer to
10600 @uref{http://gcc.gnu.org/bugs.html} for up-to-date instructions how to
10601 submit bug reports. Copies of this file in HTML (@file{bugs.html}) and
10602 plain text (@file{BUGS}) are also part of GCC releases.
10606 @chapter How To Get Help with GNU Fortran
10608 If you need help installing, using or changing GNU Fortran, there are two
10613 Look in the service directory for someone who might help you for a fee.
10614 The service directory is found in the file named @file{SERVICE} in the
10618 Send a message to @email{@value{email-help}}.
10623 @node Adding Options
10624 @chapter Adding Options
10625 @cindex options, adding
10626 @cindex adding options
10628 To add a new command-line option to @command{g77}, first decide
10629 what kind of option you wish to add.
10630 Search the @command{g77} and @command{gcc} documentation for one
10631 or more options that is most closely like the one you want to add
10632 (in terms of what kind of effect it has, and so on) to
10633 help clarify its nature.
10637 @emph{Fortran options} are options that apply only
10638 when compiling Fortran programs.
10639 They are accepted by @command{g77} and @command{gcc}, but
10640 they apply only when compiling Fortran programs.
10643 @emph{Compiler options} are options that apply
10644 when compiling most any kind of program.
10647 @emph{Fortran options} are listed in the file
10648 @file{@value{path-g77}/lang-options.h},
10649 which is used during the build of @command{gcc} to
10650 build a list of all options that are accepted by
10651 at least one language's compiler.
10652 This list goes into the @code{documented_lang_options} array
10653 in @file{gcc/toplev.c}, which uses this array to
10654 determine whether a particular option should be
10655 offered to the linked-in front end for processing
10656 by calling @code{lang_option_decode}, which, for
10657 @command{g77}, is in @file{@value{path-g77}/com.c} and just
10658 calls @code{ffe_decode_option}.
10660 If the linked-in front end ``rejects'' a
10661 particular option passed to it, @file{toplev.c}
10662 just ignores the option, because @emph{some}
10663 language's compiler is willing to accept it.
10665 This allows commands like @samp{gcc -fno-asm foo.c bar.f}
10666 to work, even though Fortran compilation does
10667 not currently support the @option{-fno-asm} option;
10668 even though the @code{f771} version of @code{lang_decode_option}
10669 rejects @option{-fno-asm}, @file{toplev.c} doesn't
10670 produce a diagnostic because some other language (C)
10673 This also means that commands like
10674 @samp{g77 -fno-asm foo.f} yield no diagnostics,
10675 despite the fact that no phase of the command was
10676 able to recognize and process @option{-fno-asm}---perhaps
10677 a warning about this would be helpful if it were
10680 Code that processes Fortran options is found in
10681 @file{@value{path-g77}/top.c}, function @code{ffe_decode_option}.
10682 This code needs to check positive and negative forms
10685 The defaults for Fortran options are set in their
10686 global definitions, also found in @file{@value{path-g77}/top.c}.
10687 Many of these defaults are actually macros defined
10688 in @file{@value{path-g77}/target.h}, since they might be
10690 However, since, in practice, GNU compilers
10691 should behave the same way on all configurations
10692 (especially when it comes to language constructs),
10693 the practice of setting defaults in @file{target.h}
10694 is likely to be deprecated and, ultimately, stopped
10695 in future versions of @command{g77}.
10697 Accessor macros for Fortran options, used by code
10698 in the @command{g77} FFE, are defined in @file{@value{path-g77}/top.h}.
10700 @emph{Compiler options} are listed in @file{gcc/toplev.c}
10701 in the array @code{f_options}.
10702 An option not listed in @code{lang_options} is
10703 looked up in @code{f_options} and handled from there.
10705 The defaults for compiler options are set in the
10706 global definitions for the corresponding variables,
10707 some of which are in @file{gcc/toplev.c}.
10709 You can set different defaults for @emph{Fortran-oriented}
10710 or @emph{Fortran-reticent} compiler options by changing
10711 the source code of @command{g77} and rebuilding.
10712 How to do this depends on the version of @command{g77}:
10715 @item G77 0.5.24 (EGCS 1.1)
10716 @itemx G77 0.5.25 (EGCS 1.2 - which became GCC 2.95)
10717 Change the @code{lang_init_options} routine in @file{gcc/gcc/f/com.c}.
10719 (Note that these versions of @command{g77}
10720 perform internal consistency checking automatically
10721 when the @option{-fversion} option is specified.)
10724 @itemx G77 0.5.24 (EGCS 1.0)
10725 Change the way @code{f771} handles the @option{-fset-g77-defaults}
10726 option, which is always provided as the first option when
10727 called by @command{g77} or @command{gcc}.
10729 This code is in @code{ffe_decode_options} in @file{@value{path-g77}/top.c}.
10730 Have it change just the variables that you want to default
10731 to a different setting for Fortran compiles compared to
10732 compiles of other languages.
10734 The @option{-fset-g77-defaults} option is passed to @code{f771}
10735 automatically because of the specification information
10736 kept in @file{@value{path-g77}/lang-specs.h}.
10737 This file tells the @command{gcc} command how to recognize,
10738 in this case, Fortran source files (those to be preprocessed,
10739 and those that are not), and further, how to invoke the
10740 appropriate programs (including @code{f771}) to process
10741 those source files.
10743 It is in @file{@value{path-g77}/lang-specs.h} that @option{-fset-g77-defaults},
10744 @option{-fversion}, and other options are passed, as appropriate,
10745 even when the user has not explicitly specified them.
10746 Other ``internal'' options such as @option{-quiet} also
10747 are passed via this mechanism.
10754 If you want to contribute to @command{g77} by doing research,
10755 design, specification, documentation, coding, or testing,
10756 the following information should give you some ideas.
10759 * Efficiency:: Make @command{g77} itself compile code faster.
10760 * Better Optimization:: Teach @command{g77} to generate faster code.
10761 * Simplify Porting:: Make @command{g77} easier to configure, build,
10763 * More Extensions:: Features many users won't know to ask for.
10764 * Machine Model:: @command{g77} should better leverage @command{gcc}.
10765 * Internals Documentation:: Make maintenance easier.
10766 * Internals Improvements:: Make internals more robust.
10767 * Better Diagnostics:: Make using @command{g77} on new code easier.
10771 @section Improve Efficiency
10774 Don't bother doing any performance analysis until most of the
10775 following items are taken care of, because there's no question
10776 they represent serious space/time problems, although some of
10777 them show up only given certain kinds of (popular) input.
10781 Improve @code{malloc} package and its uses to specify more info about
10782 memory pools and, where feasible, use obstacks to implement them.
10785 Skip over uninitialized portions of aggregate areas (arrays,
10786 @code{COMMON} areas, @code{EQUIVALENCE} areas) so zeros need not be output.
10787 This would reduce memory usage for large initialized aggregate
10788 areas, even ones with only one initialized element.
10790 As of version 0.5.18, a portion of this item has already been
10794 Prescan the statement (in @file{sta.c}) so that the nature of the statement
10795 is determined as much as possible by looking entirely at its form,
10796 and not looking at any context (previous statements, including types
10798 This would allow ripping out of the statement-confirmation,
10799 symbol retraction/confirmation, and diagnostic inhibition
10801 Plus, it would result in much-improved diagnostics.
10802 For example, @samp{CALL some-intrinsic(@dots{})}, where the intrinsic
10803 is not a subroutine intrinsic, would result actual error instead of the
10804 unimplemented-statement catch-all.
10807 Throughout @command{g77}, don't pass line/column pairs where
10808 a simple @code{ffewhere} type, which points to the error as much as is
10809 desired by the configuration, will do, and don't pass @code{ffelexToken} types
10810 where a simple @code{ffewhere} type will do.
10811 Then, allow new default
10812 configuration of @code{ffewhere} such that the source line text is not
10813 preserved, and leave it to things like Emacs' next-error function
10814 to point to them (now that @samp{next-error} supports column,
10815 or, perhaps, character-offset, numbers).
10816 The change in calling sequences should improve performance somewhat,
10817 as should not having to save source lines.
10818 (Whether this whole
10819 item will improve performance is questionable, but it should
10820 improve maintainability.)
10823 Handle @samp{DATA (A(I),I=1,1000000)/1000000*2/} more efficiently, especially
10824 as regards the assembly output.
10825 Some of this might require improving
10826 the back end, but lots of improvement in space/time required in @command{g77}
10827 itself can be fairly easily obtained without touching the back end.
10828 Maybe type-conversion, where necessary, can be speeded up as well in
10829 cases like the one shown (converting the @samp{2} into @samp{2.}).
10832 If analysis shows it to be worthwhile, optimize @file{lex.c}.
10835 Consider redesigning @file{lex.c} to not need any feedback
10836 during tokenization, by keeping track of enough parse state on its
10840 @node Better Optimization
10841 @section Better Optimization
10842 @cindex optimization, better
10843 @cindex code generation, improving
10845 Much of this work should be put off until after @command{g77} has
10846 all the features necessary for its widespread acceptance as a
10847 useful F77 compiler.
10848 However, perhaps this work can be done in parallel during
10849 the feature-adding work.
10853 Do the equivalent of the trick of putting @samp{extern inline} in front
10854 of every function definition in @code{libg2c} and #include'ing the resulting
10855 file in @command{f2c}+@command{gcc}---that is, inline all run-time-library functions
10856 that are at all worth inlining.
10857 (Some of this has already been done, such as for integral exponentiation.)
10860 When doing @samp{CHAR_VAR = CHAR_FUNC(@dots{})},
10861 and it's clear that types line up
10862 and @samp{CHAR_VAR} is addressable or not a @code{VAR_DECL},
10863 make @samp{CHAR_VAR}, not a
10864 temporary, be the receiver for @samp{CHAR_FUNC}.
10865 (This is now done for @code{COMPLEX} variables.)
10868 Design and implement Fortran-specific optimizations that don't
10869 really belong in the back end, or where the front end needs to
10870 give the back end more info than it currently does.
10873 Design and implement a new run-time library interface, with the
10874 code going into @code{libgcc} so no special linking is required to
10875 link Fortran programs using standard language features.
10877 would speed up lots of things, from I/O (using precompiled formats,
10878 doing just one, or, at most, very few, calls for arrays or array sections,
10879 and so on) to general computing (array/section implementations of
10880 various intrinsics, implementation of commonly performed loops that
10881 aren't likely to be optimally compiled otherwise, etc.).
10883 Among the important things the library would do are:
10887 Be a one-stop-shop-type
10888 library, hence shareable and usable by all, in that what are now
10889 library-build-time options in @code{libg2c} would be moved at least to the
10890 @command{g77} compile phase, if not to finer grains (such as choosing how
10891 list-directed I/O formatting is done by default at @code{OPEN} time, for
10892 preconnected units via options or even statements in the main program
10893 unit, maybe even on a per-I/O basis with appropriate pragma-like
10898 Probably requiring the new library design, change interface to
10899 normally have @code{COMPLEX} functions return their values in the way
10900 @command{gcc} would if they were declared @code{__complex__ float},
10902 the mechanism currently used by @code{CHARACTER} functions (whereby the
10903 functions are compiled as returning void and their first arg is
10904 a pointer to where to store the result).
10905 (Don't append underscores to
10906 external names for @code{COMPLEX} functions in some cases once @command{g77} uses
10907 @command{gcc} rather than @command{f2c} calling conventions.)
10910 Do something useful with @code{doiter} references where possible.
10911 For example, @samp{CALL FOO(I)} cannot modify @samp{I} if within
10912 a @code{DO} loop that uses @samp{I} as the
10913 iteration variable, and the back end might find that info useful
10914 in determining whether it needs to read @samp{I} back into a register after
10916 (It normally has to do that, unless it knows @samp{FOO} never
10917 modifies its passed-by-reference argument, which is rarely the case
10918 for Fortran-77 code.)
10921 @node Simplify Porting
10922 @section Simplify Porting
10923 @cindex porting, simplify
10924 @cindex simplify porting
10926 Making @command{g77} easier to configure, port, build, and install, either
10927 as a single-system compiler or as a cross-compiler, would be
10932 A new library (replacing @code{libg2c}) should improve portability as well as
10933 produce more optimal code.
10934 Further, @command{g77} and the new library should
10935 conspire to simplify naming of externals, such as by removing unnecessarily
10936 added underscores, and to reduce/eliminate the possibility of naming
10937 conflicts, while making debugger more straightforward.
10940 make multi-language applications more feasible, such as by providing
10941 Fortran intrinsics that get Fortran unit numbers given C @code{FILE *}
10945 Possibly related to a new library, @command{g77} should produce the equivalent
10946 of a @command{gcc} @samp{main(argc, argv)} function when it compiles a
10947 main program unit, instead of compiling something that must be
10948 called by a library
10949 implementation of @code{main()}.
10951 This would do many useful things such as
10952 provide more flexibility in terms of setting up exception handling,
10953 not requiring programmers to start their debugging sessions with
10954 @kbd{breakpoint MAIN__} followed by @kbd{run}, and so on.
10957 The GBE needs to understand the difference between alignment
10958 requirements and desires.
10959 For example, on Intel x86 machines, @command{g77} currently imposes
10960 overly strict alignment requirements, due to the back end, but it
10961 would be useful for Fortran and C programmers to be able to override
10962 these @emph{recommendations} as long as they don't violate the actual
10963 processor @emph{requirements}.
10966 @node More Extensions
10967 @section More Extensions
10968 @cindex extensions, more
10970 These extensions are not the sort of things users ask for ``by name'',
10971 but they might improve the usability of @command{g77}, and Fortran in
10972 general, in the long run.
10973 Some of these items really pertain to improving @command{g77} internals
10974 so that some popular extensions can be more easily supported.
10978 Look through all the documentation on the GNU Fortran language,
10979 dialects, compiler, missing features, bugs, and so on.
10980 Many mentions of incomplete or missing features are
10981 sprinkled throughout.
10982 It is not worth repeating them here.
10985 Consider adding a @code{NUMERIC} type to designate typeless numeric constants,
10987 The idea is to provide a forward-looking, effective
10988 replacement for things like the old-style @code{PARAMETER} statement
10990 really need typelessness in a maintainable, portable, clearly documented
10992 Maybe @code{TYPELESS} would include @code{CHARACTER}, @code{POINTER},
10993 and whatever else might come along.
10994 (This is not really a call for polymorphism per se, just
10995 an ability to express limited, syntactic polymorphism.)
10998 Support @samp{OPEN(@dots{},KEY=(@dots{}),@dots{})}.
11001 Support arbitrary file unit numbers, instead of limiting them
11002 to 0 through @samp{MXUNIT-1}.
11003 (This is a @code{libg2c} issue.)
11006 @samp{OPEN(NOSPANBLOCKS,@dots{})} is treated as
11007 @samp{OPEN(UNIT=NOSPANBLOCKS,@dots{})}, so a
11008 later @code{UNIT=} in the first example is invalid.
11009 Make sure this is what users of this feature would expect.
11012 Currently @command{g77} disallows @samp{READ(1'10)} since
11013 it is an obnoxious syntax, but
11014 supporting it might be pretty easy if needed.
11015 More details are needed, such
11016 as whether general expressions separated by an apostrophe are supported,
11017 or maybe the record number can be a general expression, and so on.
11020 Support @code{STRUCTURE}, @code{UNION}, @code{MAP}, and @code{RECORD}
11022 Currently there is no support at all
11023 for @code{%FILL} in @code{STRUCTURE} and related syntax,
11024 whereas the rest of the
11025 stuff has at least some parsing support.
11026 This requires either major
11027 changes to @code{libg2c} or its replacement.
11030 F90 and @command{g77} probably disagree about label scoping relative to
11031 @code{INTERFACE} and @code{END INTERFACE}, and their contained
11032 procedure interface bodies (blocks?).
11035 @code{ENTRY} doesn't support F90 @code{RESULT()} yet,
11036 since that was added after S8.112.
11039 Empty-statement handling (10 ;;CONTINUE;;) probably isn't consistent
11040 with the final form of the standard (it was vague at S8.112).
11043 It seems to be an ``open'' question whether a file, immediately after being
11044 @code{OPEN}ed,is positioned at the beginning, the end, or wherever---it
11045 might be nice to offer an option of opening to ``undefined'' status, requiring
11046 an explicit absolute-positioning operation to be performed before any
11047 other (besides @code{CLOSE}) to assist in making applications port to systems
11048 (some IBM?) that @code{OPEN} to the end of a file or some such thing.
11051 @node Machine Model
11052 @section Machine Model
11054 This items pertain to generalizing @command{g77}'s view of
11055 the machine model to more fully accept whatever the GBE
11056 provides it via its configuration.
11060 Switch to using @code{REAL_VALUE_TYPE} to represent floating-point constants
11061 exclusively so the target float format need not be required.
11063 means changing the way @command{g77} handles initialization of aggregate areas
11064 having more than one type, such as @code{REAL} and @code{INTEGER},
11066 it initializes them as if they were arrays of @code{char} and uses the
11067 bit patterns of the constants of the various types in them to determine
11068 what to stuff in elements of the arrays.
11071 Rely more and more on back-end info and capabilities, especially in the
11072 area of constants (where having the @command{g77} front-end's IL just store
11073 the appropriate tree nodes containing constants might be best).
11076 Suite of C and Fortran programs that a user/administrator can run on a
11077 machine to help determine the configuration for @command{g77} before building
11078 and help determine if the compiler works (especially with whatever
11079 libraries are installed) after building.
11082 @node Internals Documentation
11083 @section Internals Documentation
11085 Better info on how @command{g77} works and how to port it is needed.
11087 @xref{Front End}, which contains some information
11088 on @command{g77} internals.
11090 @node Internals Improvements
11091 @section Internals Improvements
11093 Some more items that would make @command{g77} more reliable
11094 and easier to maintain:
11098 Generally make expression handling focus
11099 more on critical syntax stuff, leaving semantics to callers.
11101 anything a caller can check, semantically, let it do so, rather
11102 than having @file{expr.c} do it.
11103 (Exceptions might include things like
11104 diagnosing @samp{FOO(I--K:)=BAR} where @samp{FOO} is a @code{PARAMETER}---if
11106 important to preserve the left-to-right-in-source order of production
11110 Come up with better naming conventions for @option{-D} to establish requirements
11111 to achieve desired implementation dialect via @file{proj.h}.
11114 Clean up used tokens and @code{ffewhere}s in @code{ffeglobal_terminate_1}.
11117 Replace @file{sta.c} @code{outpooldisp} mechanism with @code{malloc_pool_use}.
11120 Check for @code{opANY} in more places in @file{com.c}, @file{std.c},
11121 and @file{ste.c}, and get rid of the @samp{opCONVERT(opANY)} kludge
11122 (after determining if there is indeed no real need for it).
11125 Utility to read and check @file{bad.def} messages and their references in the
11126 code, to make sure calls are consistent with message templates.
11129 Search and fix @samp{&ffe@dots{}} and similar so that
11130 @samp{ffe@dots{}ptr@dots{}} macros are
11131 available instead (a good argument for wishing this could have written all
11132 this stuff in C++, perhaps).
11133 On the other hand, it's questionable whether this sort of
11134 improvement is really necessary, given the availability of
11135 tools such as Emacs and Perl, which make finding any
11136 address-taking of structure members easy enough?
11139 Some modules truly export the member names of their structures (and the
11140 structures themselves), maybe fix this, and fix other modules that just
11141 appear to as well (by appending @samp{_}, though it'd be ugly and probably
11142 not worth the time).
11145 Implement C macros @samp{RETURNS(value)} and @samp{SETS(something,value)}
11147 and use them throughout @command{g77} source code (especially in the definitions
11148 of access macros in @samp{.h} files) so they can be tailored
11149 to catch code writing into a @samp{RETURNS()} or reading from a @samp{SETS()}.
11152 Decorate throughout with @code{const} and other such stuff.
11155 All F90 notational derivations in the source code are still based
11156 on the S8.112 version of the draft standard.
11157 Probably should update
11158 to the official standard, or put documentation of the rules as used
11159 in the code@dots{}uh@dots{}in the code.
11162 Some @code{ffebld_new} calls (those outside of @file{ffeexpr.c} or
11163 inside but invoked via paths not involving @code{ffeexpr_lhs} or
11164 @code{ffeexpr_rhs}) might be creating things
11165 in improper pools, leading to such things staying around too long or
11166 (doubtful, but possible and dangerous) not long enough.
11169 Some @code{ffebld_list_new} (or whatever) calls might not be matched by
11170 @code{ffebld_list_bottom} (or whatever) calls, which might someday matter.
11171 (It definitely is not a problem just yet.)
11174 Probably not doing clean things when we fail to @code{EQUIVALENCE} something
11175 due to alignment/mismatch or other problems---they end up without
11176 @code{ffestorag} objects, so maybe the backend (and other parts of the front
11177 end) can notice that and handle like an @code{opANY} (do what it wants, just
11178 don't complain or crash).
11179 Most of this seems to have been addressed
11180 by now, but a code review wouldn't hurt.
11183 @node Better Diagnostics
11184 @section Better Diagnostics
11186 These are things users might not ask about, or that need to
11187 be looked into, before worrying about.
11188 Also here are items that involve reducing unnecessary diagnostic
11193 When @code{FUNCTION} and @code{ENTRY} point types disagree (@code{CHARACTER}
11194 lengths, type classes, and so on),
11195 @code{ANY}-ize the offending @code{ENTRY} point and any @emph{new} dummies
11199 Speed up and improve error handling for data when repeat-count is
11201 For example, don't output 20 unnecessary messages after the
11202 first necessary one for:
11207 DATA (X(I), J= 1, 20) /20*5/
11212 (The @code{CONTINUE} statement ensures the @code{DATA} statement
11213 is processed in the context of executable, not specification,
11223 @chapter Diagnostics
11224 @cindex diagnostics
11226 Some diagnostics produced by @command{g77} require sufficient explanation
11227 that the explanations are given below, and the diagnostics themselves
11228 identify the appropriate explanation.
11230 Identification uses the GNU Info format---specifically, the @command{info}
11231 command that displays the explanation is given within square
11232 brackets in the diagnostic.
11236 foo.f:5: Invalid statement [info -f g77 M FOOEY]
11239 More details about the above diagnostic is found in the @command{g77} Info
11240 documentation, menu item @samp{M}, submenu item @samp{FOOEY},
11241 which is displayed by typing the UNIX command
11242 @samp{info -f g77 M FOOEY}.
11244 Other Info readers, such as EMACS, may be just as easily used to display
11245 the pertinent node.
11246 In the above example, @samp{g77} is the Info document name,
11247 @samp{M} is the top-level menu item to select,
11248 and, in that node (named @samp{Diagnostics}, the name of
11249 this chapter, which is the very text you're reading now),
11250 @samp{FOOEY} is the menu item to select.
11253 In this printed version of the @command{g77} manual, the above example
11254 points to a section, below, entitled @samp{FOOEY}---though, of course,
11255 as the above is just a sample, no such section exists.
11259 * CMPAMBIG:: Ambiguous use of intrinsic.
11260 * EXPIMP:: Intrinsic used explicitly and implicitly.
11261 * INTGLOB:: Intrinsic also used as name of global.
11262 * LEX:: Various lexer messages
11263 * GLOBALS:: Disagreements about globals.
11264 * LINKFAIL:: When linking @code{f771} fails.
11265 * Y2KBAD:: Use of non-Y2K-compliant intrinsic.
11269 @section @code{CMPAMBIG}
11273 Ambiguous use of intrinsic @var{intrinsic} @dots{}
11276 The type of the argument to the invocation of the @var{intrinsic}
11277 intrinsic is a @code{COMPLEX} type other than @code{COMPLEX(KIND=1)}.
11278 Typically, it is @code{COMPLEX(KIND=2)}, also known as
11279 @code{DOUBLE COMPLEX}.
11281 The interpretation of this invocation depends on the particular
11282 dialect of Fortran for which the code was written.
11283 Some dialects convert the real part of the argument to
11284 @code{REAL(KIND=1)}, thus losing precision; other dialects,
11285 and Fortran 90, do no such conversion.
11287 So, GNU Fortran rejects such invocations except under certain
11288 circumstances, to avoid making an incorrect assumption that results
11289 in generating the wrong code.
11291 To determine the dialect of the program unit, perhaps even whether
11292 that particular invocation is properly coded, determine how the
11293 result of the intrinsic is used.
11295 The result of @var{intrinsic} is expected (by the original programmer)
11296 to be @code{REAL(KIND=1)} (the non-Fortran-90 interpretation) if:
11300 It is passed as an argument to a procedure that explicitly or
11301 implicitly declares that argument @code{REAL(KIND=1)}.
11304 a procedure with no @code{DOUBLE PRECISION} or @code{IMPLICIT DOUBLE PRECISION}
11305 statement specifying the dummy argument corresponding to an
11306 actual argument of @samp{REAL(Z)}, where @samp{Z} is declared
11307 @code{DOUBLE COMPLEX}, strongly suggests that the programmer
11308 expected @samp{REAL(Z)} to return @code{REAL(KIND=1)} instead
11309 of @code{REAL(KIND=2)}.
11312 It is used in a context that would otherwise not include
11313 any @code{REAL(KIND=2)} but where treating the @var{intrinsic}
11314 invocation as @code{REAL(KIND=2)} would result in unnecessary
11315 promotions and (typically) more expensive operations on the
11326 The above example suggests the programmer expected the real part
11327 of @samp{Z} to be converted to @code{REAL(KIND=1)} before being
11328 multiplied by @samp{T} (presumed, along with @samp{R} above, to
11329 be type @code{REAL(KIND=1)}).
11331 Otherwise, the conversion would have to be delayed until after
11332 the multiplication, requiring not only an extra conversion
11333 (of @samp{T} to @code{REAL(KIND=2)}), but a (typically) more
11334 expensive multiplication (a double-precision multiplication instead
11335 of a single-precision one).
11338 The result of @var{intrinsic} is expected (by the original programmer)
11339 to be @code{REAL(KIND=2)} (the Fortran 90 interpretation) if:
11343 It is passed as an argument to a procedure that explicitly or
11344 implicitly declares that argument @code{REAL(KIND=2)}.
11346 For example, a procedure specifying a @code{DOUBLE PRECISION}
11347 dummy argument corresponding to an
11348 actual argument of @samp{REAL(Z)}, where @samp{Z} is declared
11349 @code{DOUBLE COMPLEX}, strongly suggests that the programmer
11350 expected @samp{REAL(Z)} to return @code{REAL(KIND=2)} instead
11351 of @code{REAL(KIND=1)}.
11354 It is used in an expression context that includes
11355 other @code{REAL(KIND=2)} operands,
11356 or is assigned to a @code{REAL(KIND=2)} variable or array element.
11362 DOUBLE PRECISION R, T
11367 The above example suggests the programmer expected the real part
11368 of @samp{Z} to @emph{not} be converted to @code{REAL(KIND=1)}
11369 by the @code{REAL()} intrinsic.
11371 Otherwise, the conversion would have to be immediately followed
11372 by a conversion back to @code{REAL(KIND=2)}, losing
11373 the original, full precision of the real part of @code{Z},
11374 before being multiplied by @samp{T}.
11377 Once you have determined whether a particular invocation of @var{intrinsic}
11378 expects the Fortran 90 interpretation, you can:
11382 Change it to @samp{DBLE(@var{expr})} (if @var{intrinsic} is
11383 @code{REAL}) or @samp{DIMAG(@var{expr})} (if @var{intrinsic}
11385 if it expected the Fortran 90 interpretation.
11387 This assumes @var{expr} is @code{COMPLEX(KIND=2)}---if it is
11388 some other type, such as @code{COMPLEX*32}, you should use the
11389 appropriate intrinsic, such as the one to convert to @code{REAL*16}
11390 (perhaps @code{DBLEQ()} in place of @code{DBLE()}, and
11391 @code{QIMAG()} in place of @code{DIMAG()}).
11394 Change it to @samp{REAL(@var{intrinsic}(@var{expr}))},
11396 This converts to @code{REAL(KIND=1)} in all working
11400 If you don't want to change the code, and you are certain that all
11401 ambiguous invocations of @var{intrinsic} in the source file have
11402 the same expectation regarding interpretation, you can:
11406 Compile with the @command{g77} option @option{-ff90}, to enable the
11407 Fortran 90 interpretation.
11410 Compile with the @command{g77} options @samp{-fno-f90 -fugly-complex},
11411 to enable the non-Fortran-90 interpretations.
11414 @xref{REAL() and AIMAG() of Complex}, for more information on this
11417 Note: If the above suggestions don't produce enough evidence
11418 as to whether a particular program expects the Fortran 90
11419 interpretation of this ambiguous invocation of @var{intrinsic},
11420 there is one more thing you can try.
11422 If you have access to most or all the compilers used on the
11423 program to create successfully tested and deployed executables,
11424 read the documentation for, and @emph{also} test out, each compiler
11425 to determine how it treats the @var{intrinsic} intrinsic in
11427 (If all the compilers don't agree on an interpretation, there
11428 might be lurking bugs in the deployed versions of the program.)
11430 The following sample program might help:
11432 @cindex JCB003 program
11436 C Written by James Craig Burley 1997-02-23.
11438 C Determine how compilers handle non-standard REAL
11439 C and AIMAG on DOUBLE COMPLEX operands.
11447 IF (R .NE. 0.) PRINT *, 'REAL() is Fortran 90'
11448 IF (R .EQ. 0.) PRINT *, 'REAL() is not Fortran 90'
11452 IF (R .NE. 0.) PRINT *, 'AIMAG() is Fortran 90'
11453 IF (R .EQ. 0.) PRINT *, 'AIMAG() is not Fortran 90'
11456 C Just to make sure compiler doesn't use naive flow
11457 C analysis to optimize away careful work above,
11458 C which might invalidate results....
11460 SUBROUTINE DUMDUM(Z, R)
11466 If the above program prints contradictory results on a
11467 particular compiler, run away!
11470 @section @code{EXPIMP}
11474 Intrinsic @var{intrinsic} referenced @dots{}
11477 The @var{intrinsic} is explicitly declared in one program
11478 unit in the source file and implicitly used as an intrinsic
11479 in another program unit in the same source file.
11481 This diagnostic is designed to catch cases where a program
11482 might depend on using the name @var{intrinsic} as an intrinsic
11483 in one program unit and as a global name (such as the name
11484 of a subroutine or function) in another, but @command{g77} recognizes
11485 the name as an intrinsic in both cases.
11487 After verifying that the program unit making implicit use
11488 of the intrinsic is indeed written expecting the intrinsic,
11489 add an @samp{INTRINSIC @var{intrinsic}} statement to that
11490 program unit to prevent this warning.
11492 This and related warnings are disabled by using
11493 the @option{-Wno-globals} option when compiling.
11495 Note that this warning is not issued for standard intrinsics.
11496 Standard intrinsics include those described in the FORTRAN 77
11497 standard and, if @option{-ff90} is specified, those described
11498 in the Fortran 90 standard.
11499 Such intrinsics are not as likely to be confused with user
11500 procedures as intrinsics provided as extensions to the
11501 standard by @command{g77}.
11504 @section @code{INTGLOB}
11508 Same name `@var{intrinsic}' given @dots{}
11511 The name @var{intrinsic} is used for a global entity (a common
11512 block or a program unit) in one program unit and implicitly
11513 used as an intrinsic in another program unit.
11515 This diagnostic is designed to catch cases where a program
11516 intends to use a name entirely as a global name, but @command{g77}
11517 recognizes the name as an intrinsic in the program unit that
11518 references the name, a situation that would likely produce
11524 INTEGER FUNCTION TIME()
11530 PRINT *, 'Time is ', TIME()
11534 The above example defines a program unit named @samp{TIME}, but
11535 the reference to @samp{TIME} in the main program unit @samp{SAMP}
11536 is normally treated by @command{g77} as a reference to the intrinsic
11537 @code{TIME()} (unless a command-line option that prevents such
11538 treatment has been specified).
11540 As a result, the program @samp{SAMP} will @emph{not}
11541 invoke the @samp{TIME} function in the same source file.
11543 Since @command{g77} recognizes @code{libU77} procedures as
11544 intrinsics, and since some existing code uses the same names
11545 for its own procedures as used by some @code{libU77}
11546 procedures, this situation is expected to arise often enough
11547 to make this sort of warning worth issuing.
11549 After verifying that the program unit making implicit use
11550 of the intrinsic is indeed written expecting the intrinsic,
11551 add an @samp{INTRINSIC @var{intrinsic}} statement to that
11552 program unit to prevent this warning.
11554 Or, if you believe the program unit is designed to invoke the
11555 program-defined procedure instead of the intrinsic (as
11556 recognized by @command{g77}), add an @samp{EXTERNAL @var{intrinsic}}
11557 statement to the program unit that references the name to
11558 prevent this warning.
11560 This and related warnings are disabled by using
11561 the @option{-Wno-globals} option when compiling.
11563 Note that this warning is not issued for standard intrinsics.
11564 Standard intrinsics include those described in the FORTRAN 77
11565 standard and, if @option{-ff90} is specified, those described
11566 in the Fortran 90 standard.
11567 Such intrinsics are not as likely to be confused with user
11568 procedures as intrinsics provided as extensions to the
11569 standard by @command{g77}.
11572 @section @code{LEX}
11576 Unrecognized character @dots{}
11577 Invalid first character @dots{}
11578 Line too long @dots{}
11579 Non-numeric character @dots{}
11580 Continuation indicator @dots{}
11581 Label at @dots{} invalid with continuation line indicator @dots{}
11582 Character constant @dots{}
11583 Continuation line @dots{}
11584 Statement at @dots{} begins with invalid token
11587 Although the diagnostics identify specific problems, they can
11588 be produced when general problems such as the following occur:
11592 The source file contains something other than Fortran code.
11594 If the code in the file does not look like many of the examples
11595 elsewhere in this document, it might not be Fortran code.
11596 (Note that Fortran code often is written in lower case letters,
11597 while the examples in this document use upper case letters,
11598 for stylistic reasons.)
11600 For example, if the file contains lots of strange-looking
11601 characters, it might be APL source code; if it contains lots
11602 of parentheses, it might be Lisp source code; if it
11603 contains lots of bugs, it might be C++ source code.
11606 The source file contains free-form Fortran code, but @option{-ffree-form}
11607 was not specified on the command line to compile it.
11609 Free form is a newer form for Fortran code.
11610 The older, classic form is called fixed form.
11612 @cindex continuation character
11613 @cindex characters, continuation
11614 Fixed-form code is visually fairly distinctive, because
11615 numerical labels and comments are all that appear in
11616 the first five columns of a line, the sixth column is
11617 reserved to denote continuation lines,
11618 and actual statements start at or beyond column 7.
11619 Spaces generally are not significant, so if you
11620 see statements such as @samp{REALX,Y} and @samp{DO10I=1,100},
11621 you are looking at fixed-form code.
11624 Comment lines are indicated by the letter @samp{C} or the symbol
11625 @samp{*} in column 1.
11626 @cindex trailing comment
11628 @cindex characters, comment
11630 @cindex exclamation point
11631 (Some code uses @samp{!} or @samp{/*} to begin in-line comments,
11632 which many compilers support.)
11634 Free-form code is distinguished from fixed-form source
11635 primarily by the fact that statements may start anywhere.
11636 (If lots of statements start in columns 1 through 6,
11637 that's a strong indicator of free-form source.)
11638 Consecutive keywords must be separated by spaces, so
11639 @samp{REALX,Y} is not valid, while @samp{REAL X,Y} is.
11640 There are no comment lines per se, but @samp{!} starts a
11641 comment anywhere in a line (other than within a character or
11642 Hollerith constant).
11644 @xref{Source Form}, for more information.
11647 The source file is in fixed form and has been edited without
11648 sensitivity to the column requirements.
11650 Statements in fixed-form code must be entirely contained within
11651 columns 7 through 72 on a given line.
11652 Starting them ``early'' is more likely to result in diagnostics
11653 than finishing them ``late'', though both kinds of errors are
11654 often caught at compile time.
11656 For example, if the following code fragment is edited by following
11657 the commented instructions literally, the result, shown afterward,
11658 would produce a diagnostic when compiled:
11661 C On XYZZY systems, remove "C" on next line:
11665 The result of editing the above line might be:
11668 C On XYZZY systems, remove "C" on next line:
11672 However, that leaves the first @samp{C} in the @code{CALL}
11673 statement in column 6, making it a comment line, which is
11674 not really what the author intended, and which is likely
11675 to result in one of the above-listed diagnostics.
11677 @emph{Replacing} the @samp{C} in column 1 with a space
11678 is the proper change to make, to ensure the @code{CALL}
11679 keyword starts in or after column 7.
11681 Another common mistake like this is to forget that fixed-form
11682 source lines are significant through only column 72, and that,
11683 normally, any text beyond column 72 is ignored or is diagnosed
11686 @xref{Source Form}, for more information.
11689 The source file requires preprocessing, and the preprocessing
11690 is not being specified at compile time.
11692 A source file containing lines beginning with @code{#define},
11693 @code{#include}, @code{#if}, and so on is likely one that
11694 requires preprocessing.
11696 If the file's suffix is @samp{.f}, @samp{.for}, or @samp{.FOR},
11697 the file normally will be compiled @emph{without} preprocessing
11700 Change the file's suffix from @samp{.f} to @samp{.F}
11701 (or, on systems with case-insensitive file names,
11702 to @samp{.fpp} or @samp{.FPP}),
11703 from @samp{.for} to @samp{.fpp},
11704 or from @samp{.FOR} to @samp{.FPP}.
11705 @command{g77} compiles files with such names @emph{with}
11709 @cindex preprocessor
11710 @cindex cpp program
11711 @cindex programs, cpp
11712 @cindex @option{-x f77-cpp-input} option
11713 @cindex options, @option{-x f77-cpp-input}
11714 Or, learn how to use @command{gcc}'s @option{-x} option to specify
11715 the language @samp{f77-cpp-input} for Fortran files that
11716 require preprocessing.
11717 @xref{Overall Options,,Options Controlling the Kind of
11718 Output,gcc,Using the GNU Compiler Collection (GCC)}.
11721 The source file is preprocessed, and the results of preprocessing
11722 result in syntactic errors that are not necessarily obvious to
11723 someone examining the source file itself.
11725 Examples of errors resulting from preprocessor macro expansion
11726 include exceeding the line-length limit, improperly starting,
11727 terminating, or incorporating the apostrophe or double-quote in
11728 a character constant, improperly forming a Hollerith constant,
11731 @xref{Overall Options,,Options Controlling the Kind of Output},
11732 for suggestions about how to use, and not use, preprocessing
11737 @section @code{GLOBALS}
11741 Global name @var{name} defined at @dots{} already defined@dots{}
11742 Global name @var{name} at @dots{} has different type@dots{}
11743 Too many arguments passed to @var{name} at @dots{}
11744 Too few arguments passed to @var{name} at @dots{}
11745 Argument #@var{n} of @var{name} is @dots{}
11748 These messages all identify disagreements about the
11749 global procedure named @var{name} among different program units
11750 (usually including @var{name} itself).
11752 Whether a particular disagreement is reported
11753 as a warning or an error
11754 can depend on the relative order
11755 of the disagreeing portions of the source file.
11757 Disagreements between a procedure invocation
11758 and the @emph{subsequent} procedure itself
11759 are, usually, diagnosed as errors
11760 when the procedure itself @emph{precedes} the invocation.
11761 Other disagreements are diagnosed via warnings.
11763 @cindex forward references
11764 @cindex in-line code
11765 @cindex compilation, in-line
11766 This distinction, between warnings and errors,
11767 is due primarily to the present tendency of the @command{gcc} back end
11768 to inline only those procedure invocations that are
11769 @emph{preceded} by the corresponding procedure definitions.
11770 If the @command{gcc} back end is changed
11771 to inline ``forward references'',
11772 in which invocations precede definitions,
11773 the @command{g77} front end will be changed
11774 to treat both orderings as errors, accordingly.
11776 The sorts of disagreements that are diagnosed by @command{g77} include
11777 whether a procedure is a subroutine or function;
11778 if it is a function, the type of the return value of the procedure;
11779 the number of arguments the procedure accepts;
11780 and the type of each argument.
11782 Disagreements regarding global names among program units
11783 in a Fortran program @emph{should} be fixed in the code itself.
11784 However, if that is not immediately practical,
11785 and the code has been working for some time,
11786 it is possible it will work
11787 when compiled with the @option{-fno-globals} option.
11789 The @option{-fno-globals} option
11790 causes these diagnostics to all be warnings
11791 and disables all inlining of references to global procedures
11792 (to avoid subsequent compiler crashes and bad-code generation).
11793 Use of the @option{-Wno-globals} option as well as @option{-fno-globals}
11794 suppresses all of these diagnostics.
11795 (@option{-Wno-globals} by itself disables only the warnings,
11798 After using @option{-fno-globals} to work around these problems,
11799 it is wise to stop using that option and address them by fixing
11800 the Fortran code, because such problems, while they might not
11801 actually result in bugs on some systems, indicate that the code
11802 is not as portable as it could be.
11803 In particular, the code might appear to work on a particular
11804 system, but have bugs that affect the reliability of the data
11805 without exhibiting any other outward manifestations of the bugs.
11808 @section @code{LINKFAIL}
11811 On AIX 4.1, @command{g77} might not build with the native (non-GNU) tools
11812 due to a linker bug in coping with the @option{-bbigtoc} option which
11813 leads to a @samp{Relocation overflow} error. The GNU linker is not
11814 recommended on current AIX versions, though; it was developed under a
11815 now-unsupported version. This bug is said to be fixed by `update PTF
11816 U455193 for APAR IX75823'.
11818 Compiling with @option{-mminimal-toc}
11819 might solve this problem, e.g.@: by adding
11821 BOOT_CFLAGS='-mminimal-toc -O2 -g'
11823 to the @code{make bootstrap} command line.
11826 @section @code{Y2KBAD}
11827 @cindex Y2K compliance
11828 @cindex Year 2000 compliance
11832 Intrinsic `@var{name}', invoked at (^), known to be non-Y2K-compliant@dots{}
11835 This diagnostic indicates that
11836 the specific intrinsic invoked by the name @var{name}
11837 is known to have an interface
11838 that is not Year-2000 (Y2K) compliant.
11840 @xref{Year 2000 (Y2K) Problems}.
11844 @node Keyword Index
11845 @unnumbered Keyword Index