diff options
Diffstat (limited to 'gcc/f/g77.texi')
| -rw-r--r-- | gcc/f/g77.texi | 11848 |
1 files changed, 11848 insertions, 0 deletions
diff --git a/gcc/f/g77.texi b/gcc/f/g77.texi new file mode 100644 index 00000000000..3d5f83d3da6 --- /dev/null +++ b/gcc/f/g77.texi @@ -0,0 +1,11848 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename g77.info + +@set last-update 2004-03-21 +@set copyrights-g77 1995,1996,1997,1998,1999,2000,2001,2002,2003,2004 + +@include root.texi + +@c This tells @include'd files that they're part of the overall G77 doc +@c set. (They might be part of a higher-level doc set too.) +@set DOC-G77 + +@c @setfilename useg77.info +@c @setfilename portg77.info +@c To produce the full manual, use the "g77.info" setfilename, and +@c make sure the following do NOT begin with '@c' (and the @clear lines DO) +@set INTERNALS +@set USING +@c To produce a user-only manual, use the "useg77.info" setfilename, and +@c make sure the following does NOT begin with '@c': +@c @clear INTERNALS +@c To produce a porter-only manual, use the "portg77.info" setfilename, +@c and make sure the following does NOT begin with '@c': +@c @clear USING + +@ifset INTERNALS +@ifset USING +@settitle Using and Porting GNU Fortran +@end ifset +@end ifset +@c seems reasonable to assume at least one of INTERNALS or USING is set... +@ifclear INTERNALS +@settitle Using GNU Fortran +@end ifclear +@ifclear USING +@settitle Porting GNU Fortran +@end ifclear +@c then again, have some fun +@ifclear INTERNALS +@ifclear USING +@settitle Doing Squat with GNU Fortran +@end ifclear +@end ifclear + +@syncodeindex fn cp +@syncodeindex vr cp +@c %**end of header + +@c Cause even numbered pages to be printed on the left hand side of +@c the page and odd numbered pages to be printed on the right hand +@c side of the page. Using this, you can print on both sides of a +@c sheet of paper and have the text on the same part of the sheet. + +@c The text on right hand pages is pushed towards the right hand +@c margin and the text on left hand pages is pushed toward the left +@c hand margin. +@c (To provide the reverse effect, set bindingoffset to -0.75in.) + +@c @tex +@c \global\bindingoffset=0.75in +@c \global\normaloffset =0.75in +@c @end tex + +@copying +Copyright @copyright{} @value{copyrights-g77} Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'' and ``Funding +Free Software'', the Front-Cover +texts being (a) (see below), and with the Back-Cover Texts being (b) +(see below). A copy of the license is included in the section entitled +``GNU Free Documentation License''. + +(a) The FSF's Front-Cover Text is: + + A GNU Manual + +(b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. +@end copying + +@ifinfo +@dircategory Programming +@direntry +* g77: (g77). The GNU Fortran compiler. +@end direntry +@ifset INTERNALS +@ifset USING +This file documents the use and the internals of the GNU Fortran (@command{g77}) +compiler. +It corresponds to the @value{which-g77} version of @command{g77}. +@end ifset +@end ifset +@ifclear USING +This file documents the internals of the GNU Fortran (@command{g77}) compiler. +It corresponds to the @value{which-g77} version of @command{g77}. +@end ifclear +@ifclear INTERNALS +This file documents the use of the GNU Fortran (@command{g77}) compiler. +It corresponds to the @value{which-g77} version of @command{g77}. +@end ifclear + +Published by the Free Software Foundation +59 Temple Place - Suite 330 +Boston, MA 02111-1307 USA + +@insertcopying +@end ifinfo + +Contributed by James Craig Burley (@email{@value{email-burley}}). +Inspired by a first pass at translating @file{g77-0.5.16/f/DOC} that +was contributed to Craig by David Ronis (@email{ronis@@onsager.chem.mcgill.ca}). + +@setchapternewpage odd +@titlepage +@ifset INTERNALS +@ifset USING +@center @titlefont{Using and Porting GNU Fortran} + +@end ifset +@end ifset +@ifclear INTERNALS +@title Using GNU Fortran +@end ifclear +@ifclear USING +@title Porting GNU Fortran +@end ifclear +@sp 2 +@center James Craig Burley +@sp 3 +@center Last updated @value{last-update} +@sp 1 +@center for version @value{which-g77} +@page +@vskip 0pt plus 1filll +For the @value{which-g77} Version* +@sp 1 +Published by the Free Software Foundation @* +59 Temple Place - Suite 330@* +Boston, MA 02111-1307, USA@* +@c Last printed ??ber, 19??.@* +@c Printed copies are available for $? each.@* +@c ISBN ??? +@sp 1 +@insertcopying +@end titlepage +@summarycontents +@contents +@page + +@node Top, Copying,, (DIR) +@top Introduction +@cindex Introduction + +@ifset INTERNALS +@ifset USING +This manual documents how to run, install and port @command{g77}, +as well as its new features and incompatibilities, +and how to report bugs. +It corresponds to the @value{which-g77} version of @command{g77}. +@end ifset +@end ifset + +@ifclear INTERNALS +This manual documents how to run and install @command{g77}, +as well as its new features and incompatibilities, and how to report +bugs. +It corresponds to the @value{which-g77} version of @command{g77}. +@end ifclear +@ifclear USING +This manual documents how to port @command{g77}, +as well as its new features and incompatibilities, +and how to report bugs. +It corresponds to the @value{which-g77} version of @command{g77}. +@end ifclear + +@ifset DEVELOPMENT +@emph{Warning:} This document is still under development, +and might not accurately reflect the @command{g77} code base +of which it is a part. +Efforts are made to keep it somewhat up-to-date, +but they are particularly concentrated +on any version of this information +that is distributed as part of a @emph{released} @command{g77}. + +In particular, while this document is intended to apply to +the @value{which-g77} version of @command{g77}, +only an official @emph{release} of that version +is expected to contain documentation that is +most consistent with the @command{g77} product in that version. +@end ifset + +@menu +* Copying:: GNU General Public License says + how you can copy and share GNU Fortran. +* GNU Free Documentation License:: + How you can copy and share this manual. +* Contributors:: People who have contributed to GNU Fortran. +* Funding:: How to help assure continued work for free software. +* Funding GNU Fortran:: How to help assure continued work on GNU Fortran. +@ifset USING +* Getting Started:: Finding your way around this manual. +* What is GNU Fortran?:: How @command{g77} fits into the universe. +* G77 and GCC:: You can compile Fortran, C, or other programs. +* Invoking G77:: Command options supported by @command{g77}. +* News:: News about recent releases of @command{g77}. +* Changes:: User-visible changes to recent releases of @command{g77}. +* Language:: The GNU Fortran language. +* Compiler:: The GNU Fortran compiler. +* Other Dialects:: Dialects of Fortran supported by @command{g77}. +* Other Compilers:: Fortran compilers other than @command{g77}. +* Other Languages:: Languages other than Fortran. +* Debugging and Interfacing:: How @command{g77} generates code. +* Collected Fortran Wisdom:: How to avoid Trouble. +* Trouble:: If you have trouble with GNU Fortran. +* Open Questions:: Things we'd like to know. +* Bugs:: How, why, and where to report bugs. +* Service:: How to find suppliers of support for GNU Fortran. +@end ifset +@ifset INTERNALS +* Adding Options:: Guidance on teaching @command{g77} about new options. +* Projects:: Projects for @command{g77} internals hackers. +* Front End:: Design and implementation of the @command{g77} front end. +@end ifset + +* M: Diagnostics. Diagnostics produced by @command{g77}. + +* Keyword Index:: Index of concepts and symbol names. +@end menu +@c yes, the "M: " @emph{is} intentional -- bad.def references it (CMPAMBIG)! + +@include gpl.texi + +@include fdl.texi + +@node Contributors +@unnumbered Contributors to GNU Fortran +@cindex contributors +@cindex credits + +In addition to James Craig Burley, who wrote the front end, +many people have helped create and improve GNU Fortran. + +@itemize @bullet +@item +The packaging and compiler portions of GNU Fortran are based largely +on the GCC compiler. +@xref{Contributors,,Contributors to GCC,gcc,Using the GNU Compiler +Collection (GCC)}, +for more information. + +@item +The run-time library used by GNU Fortran is a repackaged version +of the @code{libf2c} library (combined from the @code{libF77} and +@code{libI77} libraries) provided as part of @command{f2c}, available for +free from @code{netlib} sites on the Internet. + +@item +Cygnus Support and The Free Software Foundation contributed +significant money and/or equipment to Craig's efforts. + +@item +The following individuals served as alpha testers prior to @command{g77}'s +public release. This work consisted of testing, researching, sometimes +debugging, and occasionally providing small amounts of code and fixes +for @command{g77}, plus offering plenty of helpful advice to Craig: + +@itemize @w{} +@item +Jonathan Corbet +@item +Dr.@: Mark Fernyhough +@item +Takafumi Hayashi (The University of Aizu)---@email{takafumi@@u-aizu.ac.jp} +@item +Kate Hedstrom +@item +Michel Kern (INRIA and Rice University)---@email{Michel.Kern@@inria.fr} +@item +Dr.@: A. O. V. Le Blanc +@item +Dave Love +@item +Rick Lutowski +@item +Toon Moene +@item +Rick Niles +@item +Derk Reefman +@item +Wayne K. Schroll +@item +Bill Thorson +@item +Pedro A. M. Vazquez +@item +Ian Watson +@end itemize + +@item +Dave Love (@email{d.love@@dl.ac.uk}) +wrote the libU77 part of the run-time library. + +@item +Scott Snyder (@email{snyder@@d0sgif.fnal.gov}) +provided the patch to add rudimentary support +for @code{INTEGER*1}, @code{INTEGER*2}, and +@code{LOGICAL*1}. +This inspired Craig to add further support, +even though the resulting support +would still be incomplete. +This support is believed to be completed at version 3.4 +of @command{gcc} by Roger Sayle (@email{roger@@eyesopen.com}). + +@item +David Ronis (@email{ronis@@onsager.chem.mcgill.ca}) inspired +and encouraged Craig to rewrite the documentation in texinfo +format by contributing a first pass at a translation of the +old @file{g77-0.5.16/f/DOC} file. + +@item +Toon Moene (@email{toon@@moene.indiv.nluug.nl}) performed +some analysis of generated code as part of an overall project +to improve @command{g77} code generation to at least be as good +as @command{f2c} used in conjunction with @command{gcc}. +So far, this has resulted in the three, somewhat +experimental, options added by @command{g77} to the @command{gcc} +compiler and its back end. + +(These, in turn, had made their way into the @code{egcs} +version of the compiler, and do not exist in @command{gcc} +version 2.8 or versions of @command{g77} based on that version +of @command{gcc}.) + +@item +John Carr (@email{jfc@@mit.edu}) wrote the alias analysis improvements. + +@item +Thanks to Mary Cortani and the staff at Craftwork Solutions +(@email{support@@craftwork.com}) for all of their support. + +@item +Many other individuals have helped debug, test, and improve @command{g77} +over the past several years, and undoubtedly more people +will be doing so in the future. +If you have done so, and would like +to see your name listed in the above list, please ask! +The default is that people wish to remain anonymous. +@end itemize + +@include funding.texi + +@node Funding GNU Fortran +@chapter Funding GNU Fortran +@cindex funding improvements +@cindex improvements, funding + +James Craig Burley (@email{@value{email-burley}}), the original author +of @command{g77}, stopped working on it in September 1999 +(He has a web page at @uref{@value{www-burley}}.) + +GNU Fortran is currently maintained by Toon Moene +(@email{toon@@moene.indiv.nluug.nl}), with the help of countless other +volunteers. + +As with other GNU software, funding is important because it can pay for +needed equipment, personnel, and so on. + +@cindex FSF, funding the +@cindex funding the FSF +The FSF provides information on the best way to fund ongoing +development of GNU software (such as GNU Fortran) in documents +such as the ``GNUS Bulletin''. +Email @email{gnu@@gnu.org} for information on funding the FSF. + +Another important way to support work on GNU Fortran is to volunteer +to help out. + +Email @email{@value{email-general}} to volunteer for this work. + +However, we strongly expect that there will never be a version 0.6 +of @command{g77}. Work on this compiler has stopped as of the release +of GCC 3.1, except for bug fixing. @command{g77} will be succeeded by +@command{g95} - see @uref{http://g95.sourceforge.net}. + +@xref{Funding,,Funding Free Software}, for more information. + +@node Getting Started +@chapter Getting Started +@cindex getting started +@cindex new users +@cindex newbies +@cindex beginners + +If you don't need help getting started reading the portions +of this manual that are most important to you, you should skip +this portion of the manual. + +If you are new to compilers, especially Fortran compilers, or +new to how compilers are structured under UNIX and UNIX-like +systems, you'll want to see @ref{What is GNU Fortran?}. + +If you are new to GNU compilers, or have used only one GNU +compiler in the past and not had to delve into how it lets +you manage various versions and configurations of @command{gcc}, +you should see @ref{G77 and GCC}. + +Everyone except experienced @command{g77} users should +see @ref{Invoking G77}. + +If you're acquainted with previous versions of @command{g77}, +you should see @ref{News,,News About GNU Fortran}. +Further, if you've actually used previous versions of @command{g77}, +especially if you've written or modified Fortran code to +be compiled by previous versions of @command{g77}, you +should see @ref{Changes}. + +If you intend to write or otherwise compile code that is +not already strictly conforming ANSI FORTRAN 77---and this +is probably everyone---you should see @ref{Language}. + +If you run into trouble getting Fortran code to compile, +link, run, or work properly, you might find answers +if you see @ref{Debugging and Interfacing}, +see @ref{Collected Fortran Wisdom}, +and see @ref{Trouble}. +You might also find that the problems you are encountering +are bugs in @command{g77}---see @ref{Bugs}, for information on +reporting them, after reading the other material. + +If you need further help with @command{g77}, or with +freely redistributable software in general, +see @ref{Service}. + +If you would like to help the @command{g77} project, +see @ref{Funding GNU Fortran}, for information on +helping financially, and see @ref{Projects}, for information +on helping in other ways. + +If you're generally curious about the future of +@command{g77}, see @ref{Projects}. +If you're curious about its past, +see @ref{Contributors}, +and see @ref{Funding GNU Fortran}. + +To see a few of the questions maintainers of @command{g77} have, +and that you might be able to answer, +see @ref{Open Questions}. + +@ifset USING +@node What is GNU Fortran? +@chapter What is GNU Fortran? +@cindex concepts, basic +@cindex basic concepts + +GNU Fortran, or @command{g77}, is designed initially as a free replacement +for, or alternative to, the UNIX @command{f77} command. +(Similarly, @command{gcc} is designed as a replacement +for the UNIX @command{cc} command.) + +@command{g77} also is designed to fit in well with the other +fine GNU compilers and tools. + +Sometimes these design goals conflict---in such cases, resolution +often is made in favor of fitting in well with Project GNU. +These cases are usually identified in the appropriate +sections of this manual. + +@cindex compilers +As compilers, @command{g77}, @command{gcc}, and @command{f77} +share the following characteristics: + +@itemize @bullet +@cindex source code +@cindex file, source +@cindex code, source +@cindex source file +@item +They read a user's program, stored in a file and +containing instructions written in the appropriate +language (Fortran, C, and so on). +This file contains @dfn{source code}. + +@cindex translation of user programs +@cindex machine code +@cindex code, machine +@cindex mistakes +@item +They translate the user's program into instructions +a computer can carry out more quickly than it takes +to translate the instructions in the first place. +These instructions are called @dfn{machine code}---code +designed to be efficiently translated and processed +by a machine such as a computer. +Humans usually aren't as good writing machine code +as they are at writing Fortran or C, because +it is easy to make tiny mistakes writing machine code. +When writing Fortran or C, it is easy +to make big mistakes. + +@cindex debugger +@cindex bugs, finding +@cindex @command{gdb}, command +@cindex commands, @command{gdb} +@item +They provide information in the generated machine code +that can make it easier to find bugs in the program +(using a debugging tool, called a @dfn{debugger}, +such as @command{gdb}). + +@cindex libraries +@cindex linking +@cindex @command{ld} command +@cindex commands, @command{ld} +@item +They locate and gather machine code already generated +to perform actions requested by statements in +the user's program. +This machine code is organized +into @dfn{libraries} and is located and gathered +during the @dfn{link} phase of the compilation +process. +(Linking often is thought of as a separate +step, because it can be directly invoked via the +@command{ld} command. +However, the @command{g77} and @command{gcc} +commands, as with most compiler commands, automatically +perform the linking step by calling on @command{ld} +directly, unless asked to not do so by the user.) + +@cindex language, incorrect use of +@cindex incorrect use of language +@item +They attempt to diagnose cases where the user's +program contains incorrect usages of the language. +The @dfn{diagnostics} produced by the compiler +indicate the problem and the location in the user's +source file where the problem was first noticed. +The user can use this information to locate and +fix the problem. +@cindex diagnostics, incorrect +@cindex incorrect diagnostics +@cindex error messages, incorrect +@cindex incorrect error messages +(Sometimes an incorrect usage +of the language leads to a situation where the +compiler can no longer make any sense of what +follows---while a human might be able to---and +thus ends up complaining about many ``problems'' +it encounters that, in fact, stem from just one +problem, usually the first one reported.) + +@cindex warnings +@cindex questionable instructions +@item +They attempt to diagnose cases where the user's +program contains a correct usage of the language, +but instructs the computer to do something questionable. +These diagnostics often are in the form of @dfn{warnings}, +instead of the @dfn{errors} that indicate incorrect +usage of the language. +@end itemize + +How these actions are performed is generally under the +control of the user. +Using command-line options, the user can specify +how persnickety the compiler is to be regarding +the program (whether to diagnose questionable usage +of the language), how much time to spend making +the generated machine code run faster, and so on. + +@cindex components of @command{g77} +@cindex @command{g77}, components of +@command{g77} consists of several components: + +@cindex @command{gcc}, command +@cindex commands, @command{gcc} +@itemize @bullet +@item +A modified version of the @command{gcc} command, which also might be +installed as the system's @command{cc} command. +(In many cases, @command{cc} refers to the +system's ``native'' C compiler, which +might be a non-GNU compiler, or an older version +of @command{gcc} considered more stable or that is +used to build the operating system kernel.) + +@cindex @command{g77}, command +@cindex commands, @command{g77} +@item +The @command{g77} command itself, which also might be installed as the +system's @command{f77} command. + +@cindex libg2c library +@cindex libf2c library +@cindex libraries, libf2c +@cindex libraries, libg2c +@cindex run-time, library +@item +The @code{libg2c} run-time library. +This library contains the machine code needed to support +capabilities of the Fortran language that are not directly +provided by the machine code generated by the @command{g77} +compilation phase. + +@code{libg2c} is just the unique name @command{g77} gives +to its version of @code{libf2c} to distinguish it from +any copy of @code{libf2c} installed from @command{f2c} +(or versions of @command{g77} that built @code{libf2c} under +that same name) +on the system. + +The maintainer of @code{libf2c} currently is +@email{dmg@@bell-labs.com}. + +@cindex @code{f771}, program +@cindex programs, @code{f771} +@cindex assembler +@cindex @command{as} command +@cindex commands, @command{as} +@cindex assembly code +@cindex code, assembly +@item +The compiler itself, internally named @code{f771}. + +Note that @code{f771} does not generate machine code directly---it +generates @dfn{assembly code} that is a more readable form +of machine code, leaving the conversion to actual machine code +to an @dfn{assembler}, usually named @command{as}. +@end itemize + +@command{gcc} is often thought of as ``the C compiler'' only, +but it does more than that. +Based on command-line options and the names given for files +on the command line, @command{gcc} determines which actions to perform, including +preprocessing, compiling (in a variety of possible languages), assembling, +and linking. + +@cindex driver, gcc command as +@cindex @command{gcc}, command as driver +@cindex executable file +@cindex files, executable +@cindex cc1 program +@cindex programs, cc1 +@cindex preprocessor +@cindex cpp program +@cindex programs, cpp +For example, the command @samp{gcc foo.c} @dfn{drives} the file +@file{foo.c} through the preprocessor @command{cpp}, then +the C compiler (internally named +@code{cc1}), then the assembler (usually @command{as}), then the linker +(@command{ld}), producing an executable program named @file{a.out} (on +UNIX systems). + +@cindex cc1plus program +@cindex programs, cc1plus +As another example, the command @samp{gcc foo.cc} would do much the same as +@samp{gcc foo.c}, but instead of using the C compiler named @code{cc1}, +@command{gcc} would use the C++ compiler (named @code{cc1plus}). + +@cindex @code{f771}, program +@cindex programs, @code{f771} +In a GNU Fortran installation, @command{gcc} recognizes Fortran source +files by name just like it does C and C++ source files. +It knows to use the Fortran compiler named @code{f771}, instead of +@code{cc1} or @code{cc1plus}, to compile Fortran files. + +@cindex @command{gcc}, not recognizing Fortran source +@cindex unrecognized file format +@cindex file format not recognized +Non-Fortran-related operation of @command{gcc} is generally +unaffected by installing the GNU Fortran version of @command{gcc}. +However, without the installed version of @command{gcc} being the +GNU Fortran version, @command{gcc} will not be able to compile +and link Fortran programs---and since @command{g77} uses @command{gcc} +to do most of the actual work, neither will @command{g77}! + +@cindex @command{g77}, command +@cindex commands, @command{g77} +The @command{g77} command is essentially just a front-end for +the @command{gcc} command. +Fortran users will normally use @command{g77} instead of @command{gcc}, +because @command{g77} +knows how to specify the libraries needed to link with Fortran programs +(@code{libg2c} and @code{lm}). +@command{g77} can still compile and link programs and +source files written in other languages, just like @command{gcc}. + +@cindex printing version information +@cindex version information, printing +The command @samp{g77 -v} is a quick +way to display lots of version information for the various programs +used to compile a typical preprocessed Fortran source file---this +produces much more output than @samp{gcc -v} currently does. +(If it produces an error message near the end of the output---diagnostics +from the linker, usually @command{ld}---you might +have an out-of-date @code{libf2c} that improperly handles +complex arithmetic.) +In the output of this command, the line beginning @samp{GNU Fortran Front +End} identifies the version number of GNU Fortran; immediately +preceding that line is a line identifying the version of @command{gcc} +with which that version of @command{g77} was built. + +@cindex libf2c library +@cindex libraries, libf2c +The @code{libf2c} library is distributed with GNU Fortran for +the convenience of its users, but is not part of GNU Fortran. +It contains the procedures +needed by Fortran programs while they are running. + +@cindex in-line code +@cindex code, in-line +For example, while code generated by @command{g77} is likely +to do additions, subtractions, and multiplications @dfn{in line}---in +the actual compiled code---it is not likely to do trigonometric +functions this way. + +Instead, operations like trigonometric +functions are compiled by the @code{f771} compiler +(invoked by @command{g77} when compiling Fortran code) into machine +code that, when run, calls on functions in @code{libg2c}, so +@code{libg2c} must be linked with almost every useful program +having any component compiled by GNU Fortran. +(As mentioned above, the @command{g77} command takes +care of all this for you.) + +The @code{f771} program represents most of what is unique to GNU Fortran. +While much of the @code{libg2c} component comes from +the @code{libf2c} component of @command{f2c}, +a free Fortran-to-C converter distributed by Bellcore (AT&T), +plus @code{libU77}, provided by Dave Love, +and the @command{g77} command is just a small front-end to @command{gcc}, +@code{f771} is a combination of two rather +large chunks of code. + +@cindex GNU Back End (GBE) +@cindex GBE +@cindex @command{gcc}, back end +@cindex back end, gcc +@cindex code generator +One chunk is the so-called @dfn{GNU Back End}, or GBE, +which knows how to generate fast code for a wide variety of processors. +The same GBE is used by the C, C++, and Fortran compiler programs @code{cc1}, +@code{cc1plus}, and @code{f771}, plus others. +Often the GBE is referred to as the ``gcc back end'' or +even just ``gcc''---in this manual, the term GBE is used +whenever the distinction is important. + +@cindex GNU Fortran Front End (FFE) +@cindex FFE +@cindex @command{g77}, front end +@cindex front end, @command{g77} +The other chunk of @code{f771} is the +majority of what is unique about GNU Fortran---the code that knows how +to interpret Fortran programs to determine what they are intending to +do, and then communicate that knowledge to the GBE for actual compilation +of those programs. +This chunk is called the @dfn{Fortran Front End} (FFE). +The @code{cc1} and @code{cc1plus} programs have their own front ends, +for the C and C++ languages, respectively. +These fronts ends are responsible for diagnosing +incorrect usage of their respective languages by the +programs the process, and are responsible for most of +the warnings about questionable constructs as well. +(The GBE handles producing some warnings, like those +concerning possible references to undefined variables.) + +Because so much is shared among the compilers for various languages, +much of the behavior and many of the user-selectable options for these +compilers are similar. +For example, diagnostics (error messages and +warnings) are similar in appearance; command-line +options like @option{-Wall} have generally similar effects; and the quality +of generated code (in terms of speed and size) is roughly similar +(since that work is done by the shared GBE). + +@node G77 and GCC +@chapter Compile Fortran, C, or Other Programs +@cindex compiling programs +@cindex programs, compiling + +@cindex @command{gcc}, command +@cindex commands, @command{gcc} +A GNU Fortran installation includes a modified version of the @command{gcc} +command. + +In a non-Fortran installation, @command{gcc} recognizes C, C++, +and Objective-C source files. + +In a GNU Fortran installation, @command{gcc} also recognizes Fortran source +files and accepts Fortran-specific command-line options, plus some +command-line options that are designed to cater to Fortran users +but apply to other languages as well. + +@xref{G++ and GCC,,Programming Languages Supported by GCC,gcc,Using +the GNU Compiler Collection (GCC)}, +for information on the way different languages are handled +by the GCC compiler (@command{gcc}). + +@cindex @command{g77}, command +@cindex commands, @command{g77} +Also provided as part of GNU Fortran is the @command{g77} command. +The @command{g77} command is designed to make compiling and linking Fortran +programs somewhat easier than when using the @command{gcc} command for +these tasks. +It does this by analyzing the command line somewhat and changing it +appropriately before submitting it to the @command{gcc} command. + +@cindex -v option +@cindex @command{g77} options, -v +@cindex options, -v +Use the @option{-v} option with @command{g77} +to see what is going on---the first line of output is the invocation +of the @command{gcc} command. + +@include invoke.texi + +@include news.texi + +@set USERVISONLY +@include news.texi +@clear USERVISONLY + +@node Language +@chapter The GNU Fortran Language + +@cindex standard, ANSI FORTRAN 77 +@cindex ANSI FORTRAN 77 standard +@cindex reference works +GNU Fortran supports a variety of extensions to, and dialects +of, the Fortran language. +Its primary base is the ANSI FORTRAN 77 standard, currently available on +the network at +@uref{http://www.fortran.com/fortran/F77_std/rjcnf0001.html} +or as monolithic text at +@uref{http://www.fortran.com/fortran/F77_std/f77_std.html}. +It offers some extensions that are popular among users +of UNIX @command{f77} and @command{f2c} compilers, some that +are popular among users of other compilers (such as Digital +products), some that are popular among users of the +newer Fortran 90 standard, and some that are introduced +by GNU Fortran. + +@cindex textbooks +(If you need a text on Fortran, +a few freely available electronic references have pointers from +@uref{http://www.fortran.com/F/books.html}. There is a `cooperative +net project', @cite{User Notes on Fortran Programming} at +@uref{ftp://vms.huji.ac.il/fortran/} and mirrors elsewhere; some of this +material might not apply specifically to @command{g77}.) + +Part of what defines a particular implementation of a Fortran +system, such as @command{g77}, is the particular characteristics +of how it supports types, constants, and so on. +Much of this is left up to the implementation by the various +Fortran standards and accepted practice in the industry. + +The GNU Fortran @emph{language} is described below. +Much of the material is organized along the same lines +as the ANSI FORTRAN 77 standard itself. + +@xref{Other Dialects}, for information on features @command{g77} supports +that are not part of the GNU Fortran language. + +@emph{Note}: This portion of the documentation definitely needs a lot +of work! + +@menu +Relationship to the ANSI FORTRAN 77 standard: +* Direction of Language Development:: Where GNU Fortran is headed. +* Standard Support:: Degree of support for the standard. + +Extensions to the ANSI FORTRAN 77 standard: +* Conformance:: +* Notation Used:: +* Terms and Concepts:: +* Characters Lines Sequence:: +* Data Types and Constants:: +* Expressions:: +* Specification Statements:: +* Control Statements:: +* Functions and Subroutines:: +* Scope and Classes of Names:: +* I/O:: +* Fortran 90 Features:: +@end menu + +@node Direction of Language Development +@section Direction of Language Development +@cindex direction of language development +@cindex features, language +@cindex language, features + +The purpose of the following description of the GNU Fortran +language is to promote wide portability of GNU Fortran programs. + +GNU Fortran is an evolving language, due to the +fact that @command{g77} itself is in beta test. +Some current features of the language might later +be redefined as dialects of Fortran supported by @command{g77} +when better ways to express these features are added to @command{g77}, +for example. +Such features would still be supported by +@command{g77}, but would be available only when +one or more command-line options were used. + +The GNU Fortran @emph{language} is distinct from the +GNU Fortran @emph{compilation system} (@command{g77}). + +For example, @command{g77} supports various dialects of +Fortran---in a sense, these are languages other than +GNU Fortran---though its primary +purpose is to support the GNU Fortran language, which also is +described in its documentation and by its implementation. + +On the other hand, non-GNU compilers might offer +support for the GNU Fortran language, and are encouraged +to do so. + +Currently, the GNU Fortran language is a fairly fuzzy object. +It represents something of a cross between what @command{g77} accepts +when compiling using the prevailing defaults and what this +document describes as being part of the language. + +Future versions of @command{g77} are expected to clarify the +definition of the language in the documentation. +Often, this will mean adding new features to the language, in the form +of both new documentation and new support in @command{g77}. +However, it might occasionally mean removing a feature +from the language itself to ``dialect'' status. +In such a case, the documentation would be adjusted +to reflect the change, and @command{g77} itself would likely be changed +to require one or more command-line options to continue supporting +the feature. + +The development of the GNU Fortran language is intended to strike +a balance between: + +@itemize @bullet +@item +Serving as a mostly-upwards-compatible language from the +de facto UNIX Fortran dialect as supported by @command{f77}. + +@item +Offering new, well-designed language features. +Attributes of such features include +not making existing code any harder to read +(for those who might be unaware that the new +features are not in use) and +not making state-of-the-art +compilers take longer to issue diagnostics, +among others. + +@item +Supporting existing, well-written code without gratuitously +rejecting non-standard constructs, regardless of the origin +of the code (its dialect). + +@item +Offering default behavior and command-line options to reduce +and, where reasonable, eliminate the need for programmers to make +any modifications to code that already works in existing +production environments. + +@item +Diagnosing constructs that have different meanings in different +systems, languages, and dialects, while offering clear, +less ambiguous ways to express each of the different meanings +so programmers can change their code appropriately. +@end itemize + +One of the biggest practical challenges for the developers of the +GNU Fortran language is meeting the sometimes contradictory demands +of the above items. + +For example, a feature might be widely used in one popular environment, +but the exact same code that utilizes that feature might not work +as expected---perhaps it might mean something entirely different---in +another popular environment. + +Traditionally, Fortran compilers---even portable ones---have solved this +problem by simply offering the appropriate feature to users of +the respective systems. +This approach treats users of various Fortran systems and dialects +as remote ``islands'', or camps, of programmers, and assume that these +camps rarely come into contact with each other (or, +especially, with each other's code). + +Project GNU takes a radically different approach to software and language +design, in that it assumes that users of GNU software do not necessarily +care what kind of underlying system they are using, regardless +of whether they are using software (at the user-interface +level) or writing it (for example, writing Fortran or C code). + +As such, GNU users rarely need consider just what kind of underlying +hardware (or, in many cases, operating system) they are using at any +particular time. +They can use and write software designed for a general-purpose, +widely portable, heterogeneous environment---the GNU environment. + +In line with this philosophy, GNU Fortran must evolve into a product +that is widely ported and portable not only in the sense that it can +be successfully built, installed, and run by users, but in the larger +sense that its users can use it in the same way, and expect largely the +same behaviors from it, regardless of the kind of system they are using +at any particular time. + +This approach constrains the solutions @command{g77} can use to resolve +conflicts between various camps of Fortran users. +If these two camps disagree about what a particular construct should +mean, @command{g77} cannot simply be changed to treat that particular construct as +having one meaning without comment (such as a warning), lest the users +expecting it to have the other meaning are unpleasantly surprised that +their code misbehaves when executed. + +The use of the ASCII backslash character in character constants is +an excellent (and still somewhat unresolved) example of this kind of +controversy. +@xref{Backslash in Constants}. +Other examples are likely to arise in the future, as @command{g77} developers +strive to improve its ability to accept an ever-wider variety of existing +Fortran code without requiring significant modifications to said code. + +Development of GNU Fortran is further constrained by the desire +to avoid requiring programmers to change their code. +This is important because it allows programmers, administrators, +and others to more faithfully evaluate and validate @command{g77} +(as an overall product and as new versions are distributed) +without having to support multiple versions of their programs +so that they continue to work the same way on their existing +systems (non-GNU perhaps, but possibly also earlier versions +of @command{g77}). + +@node Standard Support +@section ANSI FORTRAN 77 Standard Support +@cindex ANSI FORTRAN 77 support +@cindex standard, support for +@cindex support, FORTRAN 77 +@cindex compatibility, FORTRAN 77 +@cindex FORTRAN 77 compatibility + +GNU Fortran supports ANSI FORTRAN 77 with the following caveats. +In summary, the only ANSI FORTRAN 77 features @command{g77} doesn't +support are those that are probably rarely used in actual code, +some of which are explicitly disallowed by the Fortran 90 standard. + +@menu +* No Passing External Assumed-length:: CHAR*(*) CFUNC restriction. +* No Passing Dummy Assumed-length:: CHAR*(*) CFUNC restriction. +* No Pathological Implied-DO:: No @samp{((@dots{}, I=@dots{}), I=@dots{})}. +* No Useless Implied-DO:: No @samp{(A, I=1, 1)}. +@end menu + +@node No Passing External Assumed-length +@subsection No Passing External Assumed-length + +@command{g77} disallows passing of an external procedure +as an actual argument if the procedure's +type is declared @code{CHARACTER*(*)}. For example: + +@example +CHARACTER*(*) CFUNC +EXTERNAL CFUNC +CALL FOO(CFUNC) +END +@end example + +@noindent +It isn't clear whether the standard considers this conforming. + +@node No Passing Dummy Assumed-length +@subsection No Passing Dummy Assumed-length + +@command{g77} disallows passing of a dummy procedure +as an actual argument if the procedure's +type is declared @code{CHARACTER*(*)}. + +@example +SUBROUTINE BAR(CFUNC) +CHARACTER*(*) CFUNC +EXTERNAL CFUNC +CALL FOO(CFUNC) +END +@end example + +@noindent +It isn't clear whether the standard considers this conforming. + +@node No Pathological Implied-DO +@subsection No Pathological Implied-DO + +The @code{DO} variable for an implied-@code{DO} construct in a +@code{DATA} statement may not be used as the @code{DO} variable +for an outer implied-@code{DO} construct. For example, this +fragment is disallowed by @command{g77}: + +@smallexample +DATA ((A(I, I), I= 1, 10), I= 1, 10) /@dots{}/ +@end smallexample + +@noindent +This also is disallowed by Fortran 90, as it offers no additional +capabilities and would have a variety of possible meanings. + +Note that it is @emph{very} unlikely that any production Fortran code +tries to use this unsupported construct. + +@node No Useless Implied-DO +@subsection No Useless Implied-DO + +An array element initializer in an implied-@code{DO} construct in a +@code{DATA} statement must contain at least one reference to the @code{DO} +variables of each outer implied-@code{DO} construct. For example, +this fragment is disallowed by @command{g77}: + +@smallexample +DATA (A, I= 1, 1) /1./ +@end smallexample + +@noindent +This also is disallowed by Fortran 90, as FORTRAN 77's more permissive +requirements offer no additional capabilities. +However, @command{g77} doesn't necessarily diagnose all cases +where this requirement is not met. + +Note that it is @emph{very} unlikely that any production Fortran code +tries to use this unsupported construct. + +@node Conformance +@section Conformance + +(The following information augments or overrides the information in +Section 1.4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran +language. +Chapter 1 of that document otherwise serves as the basis +for the relevant aspects of GNU Fortran.) + +The definition of the GNU Fortran language is akin to that of +the ANSI FORTRAN 77 language in that it does not generally require +conforming implementations to diagnose cases where programs do +not conform to the language. + +However, @command{g77} as a compiler is being developed in a way that +is intended to enable it to diagnose such cases in an easy-to-understand +manner. + +A program that conforms to the GNU Fortran language should, when +compiled, linked, and executed using a properly installed @command{g77} +system, perform as described by the GNU Fortran language definition. +Reasons for different behavior include, among others: + +@itemize @bullet +@item +Use of resources (memory---heap, stack, and so on; disk space; CPU +time; etc.) exceeds those of the system. + +@item +Range and/or precision of calculations required by the program +exceeds that of the system. + +@item +Excessive reliance on behaviors that are system-dependent +(non-portable Fortran code). + +@item +Bugs in the program. + +@item +Bug in @command{g77}. + +@item +Bugs in the system. +@end itemize + +Despite these ``loopholes'', the availability of a clear specification +of the language of programs submitted to @command{g77}, as this document +is intended to provide, is considered an important aspect of providing +a robust, clean, predictable Fortran implementation. + +The definition of the GNU Fortran language, while having no special +legal status, can therefore be viewed as a sort of contract, or agreement. +This agreement says, in essence, ``if you write a program in this language, +and run it in an environment (such as a @command{g77} system) that supports +this language, the program should behave in a largely predictable way''. + +@node Notation Used +@section Notation Used in This Chapter + +(The following information augments or overrides the information in +Section 1.5 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran +language. +Chapter 1 of that document otherwise serves as the basis +for the relevant aspects of GNU Fortran.) + +In this chapter, ``must'' denotes a requirement, ``may'' denotes permission, +and ``must not'' and ``may not'' denote prohibition. +Terms such as ``might'', ``should'', and ``can'' generally add little or +nothing in the way of weight to the GNU Fortran language itself, +but are used to explain or illustrate the language. + +For example: + +@display +``The @code{FROBNITZ} statement must precede all executable +statements in a program unit, and may not specify any dummy +arguments. It may specify local or common variables and arrays. +Its use should be limited to portions of the program designed to +be non-portable and system-specific, because it might cause the +containing program unit to behave quite differently on different +systems.'' +@end display + +Insofar as the GNU Fortran language is specified, +the requirements and permissions denoted by the above sample statement +are limited to the placement of the statement and the kinds of +things it may specify. +The rest of the statement---the content regarding non-portable portions +of the program and the differing behavior of program units containing +the @code{FROBNITZ} statement---does not pertain the GNU Fortran +language itself. +That content offers advice and warnings about the @code{FROBNITZ} +statement. + +@emph{Remember:} The GNU Fortran language definition specifies +both what constitutes a valid GNU Fortran program and how, +given such a program, a valid GNU Fortran implementation is +to interpret that program. + +It is @emph{not} incumbent upon a valid GNU Fortran implementation +to behave in any particular way, any consistent way, or any +predictable way when it is asked to interpret input that is +@emph{not} a valid GNU Fortran program. + +Such input is said to have @dfn{undefined} behavior when +interpreted by a valid GNU Fortran implementation, though +an implementation may choose to specify behaviors for some +cases of inputs that are not valid GNU Fortran programs. + +Other notation used herein is that of the GNU texinfo format, +which is used to generate printed hardcopy, on-line hypertext +(Info), and on-line HTML versions, all from a single source +document. +This notation is used as follows: + +@itemize @bullet +@item +Keywords defined by the GNU Fortran language are shown +in uppercase, as in: @code{COMMON}, @code{INTEGER}, and +@code{BLOCK DATA}. + +Note that, in practice, many Fortran programs are written +in lowercase---uppercase is used in this manual as a +means to readily distinguish keywords and sample Fortran-related +text from the prose in this document. + +@item +Portions of actual sample program, input, or output text +look like this: @samp{Actual program text}. + +Generally, uppercase is used for all Fortran-specific and +Fortran-related text, though this does not always include +literal text within Fortran code. + +For example: @samp{PRINT *, 'My name is Bob'}. + +@item +A metasyntactic variable---that is, a name used in this document +to serve as a placeholder for whatever text is used by the +user or programmer---appears as shown in the following example: + +``The @code{INTEGER @var{ivar}} statement specifies that +@var{ivar} is a variable or array of type @code{INTEGER}.'' + +In the above example, any valid text may be substituted for +the metasyntactic variable @var{ivar} to make the statement +apply to a specific instance, as long as the same text is +substituted for @emph{both} occurrences of @var{ivar}. + +@item +Ellipses (``@dots{}'') are used to indicate further text that +is either unimportant or expanded upon further, elsewhere. + +@item +Names of data types are in the style of Fortran 90, in most +cases. + +@xref{Kind Notation}, for information on the relationship +between Fortran 90 nomenclature (such as @code{INTEGER(KIND=1)}) +and the more traditional, less portably concise nomenclature +(such as @code{INTEGER*4}). +@end itemize + +@node Terms and Concepts +@section Fortran Terms and Concepts + +(The following information augments or overrides the information in +Chapter 2 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran +language. +Chapter 2 of that document otherwise serves as the basis +for the relevant aspects of GNU Fortran.) + +@menu +* Syntactic Items:: +* Statements Comments Lines:: +* Scope of Names and Labels:: +@end menu + +@node Syntactic Items +@subsection Syntactic Items + +(Corresponds to Section 2.2 of ANSI X3.9-1978 FORTRAN 77.) + +@cindex limits, lengths of names +In GNU Fortran, a symbolic name is at least one character long, +and has no arbitrary upper limit on length. +However, names of entities requiring external linkage (such as +external functions, external subroutines, and @code{COMMON} areas) +might be restricted to some arbitrary length by the system. +Such a restriction is no more constrained than that of one +through six characters. + +Underscores (@samp{_}) are accepted in symbol names after the first +character (which must be a letter). + +@node Statements Comments Lines +@subsection Statements, Comments, and Lines + +(Corresponds to Section 2.3 of ANSI X3.9-1978 FORTRAN 77.) + +@cindex trailing comment +@cindex comment +@cindex characters, comment +@cindex ! +@cindex exclamation point +@cindex continuation character +@cindex characters, continuation +Use of an exclamation point (@samp{!}) to begin a +trailing comment (a comment that extends to the end of the same +source line) is permitted under the following conditions: + +@itemize @bullet +@item +The exclamation point does not appear in column 6. +Otherwise, it is treated as an indicator of a continuation +line. + +@item +The exclamation point appears outside a character or Hollerith +constant. +Otherwise, the exclamation point is considered part of the +constant. + +@item +The exclamation point appears to the left of any other possible +trailing comment. +That is, a trailing comment may contain exclamation points +in their commentary text. +@end itemize + +@cindex ; +@cindex semicolon +@cindex statements, separated by semicolon +Use of a semicolon (@samp{;}) as a statement separator +is permitted under the following conditions: + +@itemize @bullet +@item +The semicolon appears outside a character or Hollerith +constant. +Otherwise, the semicolon is considered part of the +constant. + +@item +The semicolon appears to the left of a trailing comment. +Otherwise, the semicolon is considered part of that +comment. + +@item +Neither a logical @code{IF} statement nor a non-construct +@code{WHERE} statement (a Fortran 90 feature) may be +followed (in the same, possibly continued, line) by +a semicolon used as a statement separator. + +This restriction avoids the confusion +that can result when reading a line such as: + +@smallexample +IF (VALIDP) CALL FOO; CALL BAR +@end smallexample + +@noindent +Some readers might think the @samp{CALL BAR} is executed +only if @samp{VALIDP} is @code{.TRUE.}, while others might +assume its execution is unconditional. + +(At present, @command{g77} does not diagnose code that +violates this restriction.) +@end itemize + +@node Scope of Names and Labels +@subsection Scope of Symbolic Names and Statement Labels +@cindex scope + +(Corresponds to Section 2.9 of ANSI X3.9-1978 FORTRAN 77.) + +Included in the list of entities that have a scope of a +program unit are construct names (a Fortran 90 feature). +@xref{Construct Names}, for more information. + +@node Characters Lines Sequence +@section Characters, Lines, and Execution Sequence + +(The following information augments or overrides the information in +Chapter 3 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran +language. +Chapter 3 of that document otherwise serves as the basis +for the relevant aspects of GNU Fortran.) + +@menu +* Character Set:: +* Lines:: +* Continuation Line:: +* Statements:: +* Statement Labels:: +* Order:: +* INCLUDE:: +* Cpp-style directives:: +@end menu + +@node Character Set +@subsection GNU Fortran Character Set +@cindex characters + +(Corresponds to Section 3.1 of ANSI X3.9-1978 FORTRAN 77.) + +Letters include uppercase letters (the twenty-six characters +of the English alphabet) and lowercase letters (their lowercase +equivalent). +Generally, lowercase letters may be used in place of uppercase +letters, though in character and Hollerith constants, they +are distinct. + +Special characters include: + +@itemize @bullet +@item +@cindex ; +@cindex semicolon +Semicolon (@samp{;}) + +@item +@cindex ! +@cindex exclamation point +Exclamation point (@samp{!}) + +@item +@cindex " +@cindex double quote +Double quote (@samp{"}) + +@item +@cindex \ +@cindex backslash +Backslash (@samp{\}) + +@item +@cindex ? +@cindex question mark +Question mark (@samp{?}) + +@item +@cindex # +@cindex hash mark +@cindex pound sign +Hash mark (@samp{#}) + +@item +@cindex & +@cindex ampersand +Ampersand (@samp{&}) + +@item +@cindex % +@cindex percent sign +Percent sign (@samp{%}) + +@item +@cindex _ +@cindex underscore +Underscore (@samp{_}) + +@item +@cindex < +@cindex open angle +@cindex left angle +@cindex open bracket +@cindex left bracket +Open angle (@samp{<}) + +@item +@cindex > +@cindex close angle +@cindex right angle +@cindex close bracket +@cindex right bracket +Close angle (@samp{>}) + +@item +The FORTRAN 77 special characters (@key{SPC}, @samp{=}, +@samp{+}, @samp{-}, @samp{*}, @samp{/}, @samp{(}, +@samp{)}, @samp{,}, @samp{.}, @samp{$}, @samp{'}, +and @samp{:}) +@end itemize + +@cindex blank +@cindex space +@cindex SPC +Note that this document refers to @key{SPC} as @dfn{space}, +while X3.9-1978 FORTRAN 77 refers to it as @dfn{blank}. + +@node Lines +@subsection Lines +@cindex lines +@cindex source file format +@cindex source format +@cindex file, source +@cindex source code +@cindex code, source +@cindex fixed form +@cindex free form + +(Corresponds to Section 3.2 of ANSI X3.9-1978 FORTRAN 77.) + +The way a Fortran compiler views source files depends entirely on the +implementation choices made for the compiler, since those choices +are explicitly left to the implementation by the published Fortran +standards. + +The GNU Fortran language mandates a view applicable to UNIX-like +text files---files that are made up of an arbitrary number of lines, +each with an arbitrary number of characters (sometimes called stream-based +files). + +This view does not apply to types of files that are specified as +having a particular number of characters on every single line (sometimes +referred to as record-based files). + +Because a ``line in a program unit is a sequence of 72 characters'', +to quote X3.9-1978, the GNU Fortran language specifies that a +stream-based text file is translated to GNU Fortran lines as follows: + +@itemize @bullet +@item +A newline in the file is the character that represents the end of +a line of text to the underlying system. +For example, on ASCII-based systems, a newline is the @key{NL} +character, which has ASCII value 10 (decimal). + +@item +Each newline in the file serves to end the line of text that precedes +it (and that does not contain a newline). + +@item +The end-of-file marker (@code{EOF}) also serves to end the line +of text that precedes it (and that does not contain a newline). + +@item +@cindex blank +@cindex space +@cindex SPC +Any line of text that is shorter than 72 characters is padded to that length +with spaces (called ``blanks'' in the standard). + +@item +Any line of text that is longer than 72 characters is truncated to that +length, but the truncated remainder must consist entirely of spaces. + +@item +Characters other than newline and the GNU Fortran character set +are invalid. +@end itemize + +For the purposes of the remainder of this description of the GNU +Fortran language, the translation described above has already +taken place, unless otherwise specified. + +The result of the above translation is that the source file appears, +in terms of the remainder of this description of the GNU Fortran language, +as if it had an arbitrary +number of 72-character lines, each character being among the GNU Fortran +character set. + +For example, if the source file itself has two newlines in a row, +the second newline becomes, after the above translation, a single +line containing 72 spaces. + +@node Continuation Line +@subsection Continuation Line +@cindex continuation line, number of +@cindex lines, continuation +@cindex number of continuation lines +@cindex limits, continuation lines + +(Corresponds to Section 3.2.3 of ANSI X3.9-1978 FORTRAN 77.) + +A continuation line is any line that both + +@itemize @bullet +@item +Contains a continuation character, and + +@item +Contains only spaces in columns 1 through 5 +@end itemize + +A continuation character is any character of the GNU Fortran character set +other than space (@key{SPC}) or zero (@samp{0}) +in column 6, or a digit (@samp{0} through @samp{9}) in column +7 through 72 of a line that has only spaces to the left of that +digit. + +The continuation character is ignored as far as the content of +the statement is concerned. + +The GNU Fortran language places no limit on the number of +continuation lines in a statement. +In practice, the limit depends on a variety of factors, such as +available memory, statement content, and so on, but no +GNU Fortran system may impose an arbitrary limit. + +@node Statements +@subsection Statements + +(Corresponds to Section 3.3 of ANSI X3.9-1978 FORTRAN 77.) + +Statements may be written using an arbitrary number of continuation +lines. + +Statements may be separated using the semicolon (@samp{;}), except +that the logical @code{IF} and non-construct @code{WHERE} statements +may not be separated from subsequent statements using only a semicolon +as statement separator. + +The @code{END PROGRAM}, @code{END SUBROUTINE}, @code{END FUNCTION}, +and @code{END BLOCK DATA} statements are alternatives to the @code{END} +statement. +These alternatives may be written as normal statements---they are not +subject to the restrictions of the @code{END} statement. + +However, no statement other than @code{END} may have an initial line +that appears to be an @code{END} statement---even @code{END PROGRAM}, +for example, must not be written as: + +@example + END + &PROGRAM +@end example + +@node Statement Labels +@subsection Statement Labels + +(Corresponds to Section 3.4 of ANSI X3.9-1978 FORTRAN 77.) + +A statement separated from its predecessor via a semicolon may be +labeled as follows: + +@itemize @bullet +@item +The semicolon is followed by the label for the statement, +which in turn follows the label. + +@item +The label must be no more than five digits in length. + +@item +The first digit of the label for the statement is not +the first non-space character on a line. +Otherwise, that character is treated as a continuation +character. +@end itemize + +A statement may have only one label defined for it. + +@node Order +@subsection Order of Statements and Lines + +(Corresponds to Section 3.5 of ANSI X3.9-1978 FORTRAN 77.) + +Generally, @code{DATA} statements may precede executable statements. +However, specification statements pertaining to any entities +initialized by a @code{DATA} statement must precede that @code{DATA} +statement. +For example, +after @samp{DATA I/1/}, @samp{INTEGER I} is not permitted, but +@samp{INTEGER J} is permitted. + +The last line of a program unit may be an @code{END} statement, +or may be: + +@itemize @bullet +@item +An @code{END PROGRAM} statement, if the program unit is a main program. + +@item +An @code{END SUBROUTINE} statement, if the program unit is a subroutine. + +@item +An @code{END FUNCTION} statement, if the program unit is a function. + +@item +An @code{END BLOCK DATA} statement, if the program unit is a block data. +@end itemize + +@node INCLUDE +@subsection Including Source Text +@cindex INCLUDE directive + +Additional source text may be included in the processing of +the source file via the @code{INCLUDE} directive: + +@example +INCLUDE @var{filename} +@end example + +@noindent +The source text to be included is identified by @var{filename}, +which is a literal GNU Fortran character constant. +The meaning and interpretation of @var{filename} depends on the +implementation, but typically is a filename. + +(@command{g77} treats it as a filename that it searches for +in the current directory and/or directories specified +via the @option{-I} command-line option.) + +The effect of the @code{INCLUDE} directive is as if the +included text directly replaced the directive in the source +file prior to interpretation of the program. +Included text may itself use @code{INCLUDE}. +The depth of nested @code{INCLUDE} references depends on +the implementation, but typically is a positive integer. + +This virtual replacement treats the statements and @code{INCLUDE} +directives in the included text as syntactically distinct from +those in the including text. + +Therefore, the first non-comment line of the included text +must not be a continuation line. +The included text must therefore have, after the non-comment +lines, either an initial line (statement), an @code{INCLUDE} +directive, or nothing (the end of the included text). + +Similarly, the including text may end the @code{INCLUDE} +directive with a semicolon or the end of the line, but it +cannot follow an @code{INCLUDE} directive at the end of its +line with a continuation line. +Thus, the last statement in an included text may not be +continued. + +Any statements between two @code{INCLUDE} directives on the +same line are treated as if they appeared in between the +respective included texts. +For example: + +@smallexample +INCLUDE 'A'; PRINT *, 'B'; INCLUDE 'C'; END PROGRAM +@end smallexample + +@noindent +If the text included by @samp{INCLUDE 'A'} constitutes +a @samp{PRINT *, 'A'} statement and the text included by +@samp{INCLUDE 'C'} constitutes a @samp{PRINT *, 'C'} statement, +then the output of the above sample program would be + +@example +A +B +C +@end example + +@noindent +(with suitable allowances for how an implementation defines +its handling of output). + +Included text must not include itself directly or indirectly, +regardless of whether the @var{filename} used to reference +the text is the same. + +Note that @code{INCLUDE} is @emph{not} a statement. +As such, it is neither a non-executable or executable +statement. +However, if the text it includes constitutes one or more +executable statements, then the placement of @code{INCLUDE} +is subject to effectively the same restrictions as those +on executable statements. + +An @code{INCLUDE} directive may be continued across multiple +lines as if it were a statement. +This permits long names to be used for @var{filename}. + +@node Cpp-style directives +@subsection Cpp-style directives +@cindex # +@cindex preprocessor + +@code{cpp} output-style @code{#} directives +(@pxref{C Preprocessor Output,,, cpp, The C Preprocessor}) +are recognized by the compiler even +when the preprocessor isn't run on the input (as it is when compiling +@samp{.F} files). (Note the distinction between these @command{cpp} +@code{#} @emph{output} directives and @code{#line} @emph{input} +directives.) + +@node Data Types and Constants +@section Data Types and Constants + +(The following information augments or overrides the information in +Chapter 4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran +language. +Chapter 4 of that document otherwise serves as the basis +for the relevant aspects of GNU Fortran.) + +To more concisely express the appropriate types for +entities, this document uses the more concise +Fortran 90 nomenclature such as @code{INTEGER(KIND=1)} +instead of the more traditional, but less portably concise, +byte-size-based nomenclature such as @code{INTEGER*4}, +wherever reasonable. + +When referring to generic types---in contexts where the +specific precision and range of a type are not important---this +document uses the generic type names @code{INTEGER}, @code{LOGICAL}, +@code{REAL}, @code{COMPLEX}, and @code{CHARACTER}. + +In some cases, the context requires specification of a +particular type. +This document uses the @samp{KIND=} notation to accomplish +this throughout, sometimes supplying the more traditional +notation for clarification, though the traditional notation +might not work the same way on all GNU Fortran implementations. + +Use of @samp{KIND=} makes this document more concise because +@command{g77} is able to define values for @samp{KIND=} that +have the same meanings on all systems, due to the way the +Fortran 90 standard specifies these values are to be used. + +(In particular, that standard permits an implementation to +arbitrarily assign nonnegative values. +There are four distinct sets of assignments: one to the @code{CHARACTER} +type; one to the @code{INTEGER} type; one to the @code{LOGICAL} type; +and the fourth to both the @code{REAL} and @code{COMPLEX} types. +Implementations are free to assign these values in any order, +leave gaps in the ordering of assignments, and assign more than +one value to a representation.) + +This makes @samp{KIND=} values superior to the values used +in non-standard statements such as @samp{INTEGER*4}, because +the meanings of the values in those statements vary from machine +to machine, compiler to compiler, even operating system to +operating system. + +However, use of @samp{KIND=} is @emph{not} generally recommended +when writing portable code (unless, for example, the code is +going to be compiled only via @command{g77}, which is a widely +ported compiler). +GNU Fortran does not yet have adequate language constructs to +permit use of @samp{KIND=} in a fashion that would make the +code portable to Fortran 90 implementations; and, this construct +is known to @emph{not} be accepted by many popular FORTRAN 77 +implementations, so it cannot be used in code that is to be ported +to those. + +The distinction here is that this document is able to use +specific values for @samp{KIND=} to concisely document the +types of various operations and operands. + +A Fortran program should use the FORTRAN 77 designations for the +appropriate GNU Fortran types---such as @code{INTEGER} for +@code{INTEGER(KIND=1)}, @code{REAL} for @code{REAL(KIND=1)}, +and @code{DOUBLE COMPLEX} for @code{COMPLEX(KIND=2)}---and, +where no such designations exist, make use of appropriate +techniques (preprocessor macros, parameters, and so on) +to specify the types in a fashion that may be easily adjusted +to suit each particular implementation to which the program +is ported. +(These types generally won't need to be adjusted for ports of +@command{g77}.) + +Further details regarding GNU Fortran data types and constants +are provided below. + +@menu +* Types:: +* Constants:: +* Integer Type:: +* Character Type:: +@end menu + +@node Types +@subsection Data Types + +(Corresponds to Section 4.1 of ANSI X3.9-1978 FORTRAN 77.) + +GNU Fortran supports these types: + +@enumerate +@item +Integer (generic type @code{INTEGER}) + +@item +Real (generic type @code{REAL}) + +@item +Double precision + +@item +Complex (generic type @code{COMPLEX}) + +@item +Logical (generic type @code{LOGICAL}) + +@item +Character (generic type @code{CHARACTER}) + +@item +Double Complex +@end enumerate + +(The types numbered 1 through 6 above are standard FORTRAN 77 types.) + +The generic types shown above are referred to in this document +using only their generic type names. +Such references usually indicate that any specific type (kind) +of that generic type is valid. + +For example, a context described in this document as accepting +the @code{COMPLEX} type also is likely to accept the +@code{DOUBLE COMPLEX} type. + +The GNU Fortran language supports three ways to specify +a specific kind of a generic type. + +@menu +* Double Notation:: As in @code{DOUBLE COMPLEX}. +* Star Notation:: As in @code{INTEGER*4}. +* Kind Notation:: As in @code{INTEGER(KIND=1)}. +@end menu + +@node Double Notation +@subsubsection Double Notation + +The GNU Fortran language supports two uses of the keyword +@code{DOUBLE} to specify a specific kind of type: + +@itemize @bullet +@item +@code{DOUBLE PRECISION}, equivalent to @code{REAL(KIND=2)} + +@item +@code{DOUBLE COMPLEX}, equivalent to @code{COMPLEX(KIND=2)} +@end itemize + +Use one of the above forms where a type name is valid. + +While use of this notation is popular, it doesn't scale +well in a language or dialect rich in intrinsic types, +as is the case for the GNU Fortran language (especially +planned future versions of it). + +After all, one rarely sees type names such as @samp{DOUBLE INTEGER}, +@samp{QUADRUPLE REAL}, or @samp{QUARTER INTEGER}. +Instead, @code{INTEGER*8}, @code{REAL*16}, and @code{INTEGER*1} +often are substituted for these, respectively, even though they +do not always have the same meanings on all systems. +(And, the fact that @samp{DOUBLE REAL} does not exist as such +is an inconsistency.) + +Therefore, this document uses ``double notation'' only on occasion +for the benefit of those readers who are accustomed to it. + +@node Star Notation +@subsubsection Star Notation +@cindex *@var{n} notation + +The following notation specifies the storage size for a type: + +@smallexample +@var{generic-type}*@var{n} +@end smallexample + +@noindent +@var{generic-type} must be a generic type---one of +@code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL}, +or @code{CHARACTER}. +@var{n} must be one or more digits comprising a decimal +integer number greater than zero. + +Use the above form where a type name is valid. + +The @samp{*@var{n}} notation specifies that the amount of storage +occupied by variables and array elements of that type is @var{n} +times the storage occupied by a @code{CHARACTER*1} variable. + +This notation might indicate a different degree of precision and/or +range for such variables and array elements, and the functions that +return values of types using this notation. +It does not limit the precision or range of values of that type +in any particular way---use explicit code to do that. + +Further, the GNU Fortran language requires no particular values +for @var{n} to be supported by an implementation via the @samp{*@var{n}} +notation. +@command{g77} supports @code{INTEGER*1} (as @code{INTEGER(KIND=3)}) +on all systems, for example, +but not all implementations are required to do so, and @command{g77} +is known to not support @code{REAL*1} on most (or all) systems. + +As a result, except for @var{generic-type} of @code{CHARACTER}, +uses of this notation should be limited to isolated +portions of a program that are intended to handle system-specific +tasks and are expected to be non-portable. + +(Standard FORTRAN 77 supports the @samp{*@var{n}} notation for +only @code{CHARACTER}, where it signifies not only the amount +of storage occupied, but the number of characters in entities +of that type. +However, almost all Fortran compilers have supported this +notation for generic types, though with a variety of meanings +for @var{n}.) + +Specifications of types using the @samp{*@var{n}} notation +always are interpreted as specifications of the appropriate +types described in this document using the @samp{KIND=@var{n}} +notation, described below. + +While use of this notation is popular, it doesn't serve well +in the context of a widely portable dialect of Fortran, such as +the GNU Fortran language. + +For example, even on one particular machine, two or more popular +Fortran compilers might well disagree on the size of a type +declared @code{INTEGER*2} or @code{REAL*16}. +Certainly there +is known to be disagreement over such things among Fortran +compilers on @emph{different} systems. + +Further, this notation offers no elegant way to specify sizes +that are not even multiples of the ``byte size'' typically +designated by @code{INTEGER*1}. +Use of ``absurd'' values (such as @code{INTEGER*1000}) would +certainly be possible, but would perhaps be stretching the original +intent of this notation beyond the breaking point in terms +of widespread readability of documentation and code making use +of it. + +Therefore, this document uses ``star notation'' only on occasion +for the benefit of those readers who are accustomed to it. + +@node Kind Notation +@subsubsection Kind Notation +@cindex KIND= notation + +The following notation specifies the kind-type selector of a type: + +@smallexample +@var{generic-type}(KIND=@var{n}) +@end smallexample + +@noindent +Use the above form where a type name is valid. + +@var{generic-type} must be a generic type---one of +@code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL}, +or @code{CHARACTER}. +@var{n} must be an integer initialization expression that +is a positive, nonzero value. + +Programmers are discouraged from writing these values directly +into their code. +Future versions of the GNU Fortran language will offer +facilities that will make the writing of code portable +to @command{g77} @emph{and} Fortran 90 implementations simpler. + +However, writing code that ports to existing FORTRAN 77 +implementations depends on avoiding the @samp{KIND=} construct. + +The @samp{KIND=} construct is thus useful in the context +of GNU Fortran for two reasons: + +@itemize @bullet +@item +It provides a means to specify a type in a fashion that +is portable across all GNU Fortran implementations (though +not other FORTRAN 77 and Fortran 90 implementations). + +@item +It provides a sort of Rosetta stone for this document to use +to concisely describe the types of various operations and +operands. +@end itemize + +The values of @var{n} in the GNU Fortran language are +assigned using a scheme that: + +@itemize @bullet +@item +Attempts to maximize the ability of readers +of this document to quickly familiarize themselves +with assignments for popular types + +@item +Provides a unique value for each specific desired +meaning + +@item +Provides a means to automatically assign new values so +they have a ``natural'' relationship to existing values, +if appropriate, or, if no such relationship exists, will +not interfere with future values assigned on the basis +of such relationships + +@item +Avoids using values that are similar to values used +in the existing, popular @samp{*@var{n}} notation, +to prevent readers from expecting that these implied +correspondences work on all GNU Fortran implementations +@end itemize + +The assignment system accomplishes this by assigning +to each ``fundamental meaning'' of a specific type a +unique prime number. +Combinations of fundamental meanings---for example, a type +that is two times the size of some other type---are assigned +values of @var{n} that are the products of the values for +those fundamental meanings. + +A prime value of @var{n} is never given more than one fundamental +meaning, to avoid situations where some code or system +cannot reasonably provide those meanings in the form of a +single type. + +The values of @var{n} assigned so far are: + +@table @code +@item KIND=0 +This value is reserved for future use. + +The planned future use is for this value to designate, +explicitly, context-sensitive kind-type selection. +For example, the expression @samp{1D0 * 0.1_0} would +be equivalent to @samp{1D0 * 0.1D0}. + +@item KIND=1 +This corresponds to the default types for +@code{REAL}, @code{INTEGER}, @code{LOGICAL}, @code{COMPLEX}, +and @code{CHARACTER}, as appropriate. + +These are the ``default'' types described in the Fortran 90 standard, +though that standard does not assign any particular @samp{KIND=} +value to these types. + +(Typically, these are @code{REAL*4}, @code{INTEGER*4}, +@code{LOGICAL*4}, and @code{COMPLEX*8}.) + +@item KIND=2 +This corresponds to types that occupy twice as much +storage as the default types. +@code{REAL(KIND=2)} is @code{DOUBLE PRECISION} (typically @code{REAL*8}), +@code{COMPLEX(KIND=2)} is @code{DOUBLE COMPLEX} (typically @code{COMPLEX*16}), + +These are the ``double precision'' types described in the Fortran 90 +standard, +though that standard does not assign any particular @samp{KIND=} +value to these types. + +@var{n} of 4 thus corresponds to types that occupy four times +as much storage as the default types, @var{n} of 8 to types that +occupy eight times as much storage, and so on. + +The @code{INTEGER(KIND=2)} and @code{LOGICAL(KIND=2)} types +are not necessarily supported by every GNU Fortran implementation. + +@item KIND=3 +This corresponds to types that occupy as much +storage as the default @code{CHARACTER} type, +which is the same effective type as @code{CHARACTER(KIND=1)} +(making that type effectively the same as @code{CHARACTER(KIND=3)}). + +(Typically, these are @code{INTEGER*1} and @code{LOGICAL*1}.) + +@var{n} of 6 thus corresponds to types that occupy twice as +much storage as the @var{n}=3 types, @var{n} of 12 to types +that occupy four times as much storage, and so on. + +These are not necessarily supported by every GNU Fortran +implementation. + +@item KIND=5 +This corresponds to types that occupy half the +storage as the default (@var{n}=1) types. + +(Typically, these are @code{INTEGER*2} and @code{LOGICAL*2}.) + +@var{n} of 25 thus corresponds to types that occupy one-quarter +as much storage as the default types. + +These are not necessarily supported by every GNU Fortran +implementation. + +@item KIND=7 +@cindex pointers +This is valid only as @code{INTEGER(KIND=7)} and +denotes the @code{INTEGER} type that has the smallest +storage size that holds a pointer on the system. + +A pointer representable by this type is capable of uniquely +addressing a @code{CHARACTER*1} variable, array, array element, +or substring. + +(Typically this is equivalent to @code{INTEGER*4} or, +on 64-bit systems, @code{INTEGER*8}. +In a compatible C implementation, it typically would +be the same size and semantics of the C type @code{void *}.) +@end table + +Note that these are @emph{proposed} correspondences and might change +in future versions of @command{g77}---avoid writing code depending +on them while @command{g77}, and therefore the GNU Fortran language +it defines, is in beta testing. + +Values not specified in the above list are reserved to +future versions of the GNU Fortran language. + +Implementation-dependent meanings will be assigned new, +unique prime numbers so as to not interfere with other +implementation-dependent meanings, and offer the possibility +of increasing the portability of code depending on such +types by offering support for them in other GNU Fortran +implementations. + +Other meanings that might be given unique values are: + +@itemize @bullet +@item +Types that make use of only half their storage size for +representing precision and range. + +For example, some compilers offer options that cause +@code{INTEGER} types to occupy the amount of storage +that would be needed for @code{INTEGER(KIND=2)} types, but the +range remains that of @code{INTEGER(KIND=1)}. + +@item +The IEEE single floating-point type. + +@item +Types with a specific bit pattern (endianness), such as the +little-endian form of @code{INTEGER(KIND=1)}. +These could permit, conceptually, use of portable code and +implementations on data files written by existing systems. +@end itemize + +Future @emph{prime} numbers should be given meanings in as incremental +a fashion as possible, to allow for flexibility and +expressiveness in combining types. + +For example, instead of defining a prime number for little-endian +IEEE doubles, one prime number might be assigned the meaning +``little-endian'', another the meaning ``IEEE double'', and the +value of @var{n} for a little-endian IEEE double would thus +naturally be the product of those two respective assigned values. +(It could even be reasonable to have IEEE values result from the +products of prime values denoting exponent and fraction sizes +and meanings, hidden bit usage, availability and representations +of special values such as subnormals, infinities, and Not-A-Numbers +(NaNs), and so on.) + +This assignment mechanism, while not inherently required for +future versions of the GNU Fortran language, is worth using +because it could ease management of the ``space'' of supported +types much easier in the long run. + +The above approach suggests a mechanism for specifying inheritance +of intrinsic (built-in) types for an entire, widely portable +product line. +It is certainly reasonable that, unlike programmers of other languages +offering inheritance mechanisms that employ verbose names for classes +and subclasses, along with graphical browsers to elucidate the +relationships, Fortran programmers would employ +a mechanism that works by multiplying prime numbers together +and finding the prime factors of such products. + +Most of the advantages for the above scheme have been explained +above. +One disadvantage is that it could lead to the defining, +by the GNU Fortran language, of some fairly large prime numbers. +This could lead to the GNU Fortran language being declared +``munitions'' by the United States Department of Defense. + +@node Constants +@subsection Constants +@cindex constants +@cindex types, constants + +(Corresponds to Section 4.2 of ANSI X3.9-1978 FORTRAN 77.) + +A @dfn{typeless constant} has one of the following forms: + +@smallexample +'@var{binary-digits}'B +'@var{octal-digits}'O +'@var{hexadecimal-digits}'Z +'@var{hexadecimal-digits}'X +@end smallexample + +@noindent +@var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits} +are nonempty strings of characters in the set @samp{01}, @samp{01234567}, +and @samp{0123456789ABCDEFabcdef}, respectively. +(The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b} +is 11, and so on.) + +A prefix-radix constant, such as @samp{Z'ABCD'}, can optionally be +treated as typeless. @xref{Fortran Dialect Options,, Options +Controlling Fortran Dialect}, for information on the +@option{-ftypeless-boz} option. + +Typeless constants have values that depend on the context in which +they are used. + +All other constants, called @dfn{typed constants}, are interpreted---converted +to internal form---according to their inherent type. +Thus, context is @emph{never} a determining factor for the type, and hence +the interpretation, of a typed constant. +(All constants in the ANSI FORTRAN 77 language are typed constants.) + +For example, @samp{1} is always type @code{INTEGER(KIND=1)} in GNU +Fortran (called default INTEGER in Fortran 90), +@samp{9.435784839284958} is always type @code{REAL(KIND=1)} (even if the +additional precision specified is lost, and even when used in a +@code{REAL(KIND=2)} context), @samp{1E0} is always type @code{REAL(KIND=2)}, +and @samp{1D0} is always type @code{REAL(KIND=2)}. + +@node Integer Type +@subsection Integer Type + +(Corresponds to Section 4.3 of ANSI X3.9-1978 FORTRAN 77.) + +An integer constant also may have one of the following forms: + +@smallexample +B'@var{binary-digits}' +O'@var{octal-digits}' +Z'@var{hexadecimal-digits}' +X'@var{hexadecimal-digits}' +@end smallexample + +@noindent +@var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits} +are nonempty strings of characters in the set @samp{01}, @samp{01234567}, +and @samp{0123456789ABCDEFabcdef}, respectively. +(The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b} +is 11, and so on.) + +@node Character Type +@subsection Character Type + +(Corresponds to Section 4.8 of ANSI X3.9-1978 FORTRAN 77.) + +@cindex double quoted character constants +A character constant may be delimited by a pair of double quotes +(@samp{"}) instead of apostrophes. +In this case, an apostrophe within the constant represents +a single apostrophe, while a double quote is represented in +the source text of the constant by two consecutive double +quotes with no intervening spaces. + +@cindex zero-length CHARACTER +@cindex null CHARACTER strings +@cindex empty CHARACTER strings +@cindex strings, empty +@cindex CHARACTER, null +A character constant may be empty (have a length of zero). + +A character constant may include a substring specification, +The value of such a constant is the value of the substring---for +example, the value of @samp{'hello'(3:5)} is the same +as the value of @samp{'llo'}. + +@node Expressions +@section Expressions + +(The following information augments or overrides the information in +Chapter 6 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran +language. +Chapter 6 of that document otherwise serves as the basis +for the relevant aspects of GNU Fortran.) + +@menu +* %LOC():: +@end menu + +@node %LOC() +@subsection The @code{%LOC()} Construct +@cindex %LOC() construct + +@example +%LOC(@var{arg}) +@end example + +The @code{%LOC()} construct is an expression +that yields the value of the location of its argument, +@var{arg}, in memory. +The size of the type of the expression depends on the system---typically, +it is equivalent to either @code{INTEGER(KIND=1)} or @code{INTEGER(KIND=2)}, +though it is actually type @code{INTEGER(KIND=7)}. + +The argument to @code{%LOC()} must be suitable as the +left-hand side of an assignment statement. +That is, it may not be a general expression involving +operators such as addition, subtraction, and so on, +nor may it be a constant. + +Use of @code{%LOC()} is recommended only for code that +is accessing facilities outside of GNU Fortran, such as +operating system or windowing facilities. +It is best to constrain such uses to isolated portions of +a program---portions that deal specifically and exclusively +with low-level, system-dependent facilities. +Such portions might well provide a portable interface for +use by the program as a whole, but are themselves not +portable, and should be thoroughly tested each time they +are rebuilt using a new compiler or version of a compiler. + +Do not depend on @code{%LOC()} returning a pointer that +can be safely used to @emph{define} (change) the argument. +While this might work in some circumstances, it is hard +to predict whether it will continue to work when a program +(that works using this unsafe behavior) +is recompiled using different command-line options or +a different version of @command{g77}. + +Generally, @code{%LOC()} is safe when used as an argument +to a procedure that makes use of the value of the corresponding +dummy argument only during its activation, and only when +such use is restricted to referencing (reading) the value +of the argument to @code{%LOC()}. + +@emph{Implementation Note:} Currently, @command{g77} passes +arguments (those not passed using a construct such as @code{%VAL()}) +by reference or descriptor, depending on the type of +the actual argument. +Thus, given @samp{INTEGER I}, @samp{CALL FOO(I)} would +seem to mean the same thing as @samp{CALL FOO(%VAL(%LOC(I)))}, and +in fact might compile to identical code. + +However, @samp{CALL FOO(%VAL(%LOC(I)))} emphatically means +``pass, by value, the address of @samp{I} in memory''. +While @samp{CALL FOO(I)} might use that same approach in a +particular version of @command{g77}, another version or compiler +might choose a different implementation, such as copy-in/copy-out, +to effect the desired behavior---and which will therefore not +necessarily compile to the same code as would +@samp{CALL FOO(%VAL(%LOC(I)))} +using the same version or compiler. + +@xref{Debugging and Interfacing}, for detailed information on +how this particular version of @command{g77} implements various +constructs. + +@node Specification Statements +@section Specification Statements + +(The following information augments or overrides the information in +Chapter 8 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran +language. +Chapter 8 of that document otherwise serves as the basis +for the relevant aspects of GNU Fortran.) + +@menu +* NAMELIST:: +* DOUBLE COMPLEX:: +@end menu + +@node NAMELIST +@subsection @code{NAMELIST} Statement +@cindex NAMELIST statement +@cindex statements, NAMELIST + +The @code{NAMELIST} statement, and related I/O constructs, are +supported by the GNU Fortran language in essentially the same +way as they are by @command{f2c}. + +This follows Fortran 90 with the restriction that on @code{NAMELIST} +input, subscripts must have the form +@smallexample +@var{subscript} [ @code{:} @var{subscript} [ @code{:} @var{stride}]] +@end smallexample +i.e.@: +@smallexample +&xx x(1:3,8:10:2)=1,2,3,4,5,6/ +@end smallexample +is allowed, but not, say, +@smallexample +&xx x(:3,8::2)=1,2,3,4,5,6/ +@end smallexample + +As an extension of the Fortran 90 form, @code{$} and @code{$END} may be +used in place of @code{&} and @code{/} in @code{NAMELIST} input, so that +@smallexample +$&xx x(1:3,8:10:2)=1,2,3,4,5,6 $end +@end smallexample +could be used instead of the example above. + +@node DOUBLE COMPLEX +@subsection @code{DOUBLE COMPLEX} Statement +@cindex DOUBLE COMPLEX + +@code{DOUBLE COMPLEX} is a type-statement (and type) that +specifies the type @code{COMPLEX(KIND=2)} in GNU Fortran. + +@node Control Statements +@section Control Statements + +(The following information augments or overrides the information in +Chapter 11 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran +language. +Chapter 11 of that document otherwise serves as the basis +for the relevant aspects of GNU Fortran.) + +@menu +* DO WHILE:: +* END DO:: +* Construct Names:: +* CYCLE and EXIT:: +@end menu + +@node DO WHILE +@subsection DO WHILE +@cindex DO WHILE +@cindex DO +@cindex MIL-STD 1753 + +The @code{DO WHILE} statement, a feature of both the MIL-STD 1753 and +Fortran 90 standards, is provided by the GNU Fortran language. +The Fortran 90 ``do forever'' statement comprising just @code{DO} is +also supported. + +@node END DO +@subsection END DO +@cindex END DO +@cindex MIL-STD 1753 + +The @code{END DO} statement is provided by the GNU Fortran language. + +This statement is used in one of two ways: + +@itemize @bullet +@item +The Fortran 90 meaning, in which it specifies the termination +point of a single @code{DO} loop started with a @code{DO} statement +that specifies no termination label. + +@item +The MIL-STD 1753 meaning, in which it specifies the termination +point of one or more @code{DO} loops, all of which start with a +@code{DO} statement that specify the label defined for the +@code{END DO} statement. + +This kind of @code{END DO} statement is merely a synonym for +@code{CONTINUE}, except it is permitted only when the statement +is labeled and a target of one or more labeled @code{DO} loops. + +It is expected that this use of @code{END DO} will be removed from +the GNU Fortran language in the future, though it is likely that +it will long be supported by @command{g77} as a dialect form. +@end itemize + +@node Construct Names +@subsection Construct Names +@cindex construct names + +The GNU Fortran language supports construct names as defined +by the Fortran 90 standard. +These names are local to the program unit and are defined +as follows: + +@smallexample +@var{construct-name}: @var{block-statement} +@end smallexample + +@noindent +Here, @var{construct-name} is the construct name itself; +its definition is connoted by the single colon (@samp{:}); and +@var{block-statement} is an @code{IF}, @code{DO}, +or @code{SELECT CASE} statement that begins a block. + +A block that is given a construct name must also specify the +same construct name in its termination statement: + +@example +END @var{block} @var{construct-name} +@end example + +@noindent +Here, @var{block} must be @code{IF}, @code{DO}, or @code{SELECT}, +as appropriate. + +@node CYCLE and EXIT +@subsection The @code{CYCLE} and @code{EXIT} Statements + +@cindex CYCLE statement +@cindex EXIT statement +@cindex statements, CYCLE +@cindex statements, EXIT +The @code{CYCLE} and @code{EXIT} statements specify that +the remaining statements in the current iteration of a +particular active (enclosing) @code{DO} loop are to be skipped. + +@code{CYCLE} specifies that these statements are skipped, +but the @code{END DO} statement that marks the end of the +@code{DO} loop be executed---that is, the next iteration, +if any, is to be started. +If the statement marking the end of the @code{DO} loop is +not @code{END DO}---in other words, if the loop is not +a block @code{DO}---the @code{CYCLE} statement does not +execute that statement, but does start the next iteration (if any). + +@code{EXIT} specifies that the loop specified by the +@code{DO} construct is terminated. + +The @code{DO} loop affected by @code{CYCLE} and @code{EXIT} +is the innermost enclosing @code{DO} loop when the following +forms are used: + +@example +CYCLE +EXIT +@end example + +Otherwise, the following forms specify the construct name +of the pertinent @code{DO} loop: + +@example +CYCLE @var{construct-name} +EXIT @var{construct-name} +@end example + +@code{CYCLE} and @code{EXIT} can be viewed as glorified @code{GO TO} +statements. +However, they cannot be easily thought of as @code{GO TO} statements +in obscure cases involving FORTRAN 77 loops. +For example: + +@smallexample + DO 10 I = 1, 5 + DO 10 J = 1, 5 + IF (J .EQ. 5) EXIT + DO 10 K = 1, 5 + IF (K .EQ. 3) CYCLE +10 PRINT *, 'I=', I, ' J=', J, ' K=', K +20 CONTINUE +@end smallexample + +@noindent +In particular, neither the @code{EXIT} nor @code{CYCLE} statements +above are equivalent to a @code{GO TO} statement to either label +@samp{10} or @samp{20}. + +To understand the effect of @code{CYCLE} and @code{EXIT} in the +above fragment, it is helpful to first translate it to its equivalent +using only block @code{DO} loops: + +@smallexample + DO I = 1, 5 + DO J = 1, 5 + IF (J .EQ. 5) EXIT + DO K = 1, 5 + IF (K .EQ. 3) CYCLE +10 PRINT *, 'I=', I, ' J=', J, ' K=', K + END DO + END DO + END DO +20 CONTINUE +@end smallexample + +Adding new labels allows translation of @code{CYCLE} and @code{EXIT} +to @code{GO TO} so they may be more easily understood by programmers +accustomed to FORTRAN coding: + +@smallexample + DO I = 1, 5 + DO J = 1, 5 + IF (J .EQ. 5) GOTO 18 + DO K = 1, 5 + IF (K .EQ. 3) GO TO 12 +10 PRINT *, 'I=', I, ' J=', J, ' K=', K +12 END DO + END DO +18 END DO +20 CONTINUE +@end smallexample + +@noindent +Thus, the @code{CYCLE} statement in the innermost loop skips over +the @code{PRINT} statement as it begins the next iteration of the +loop, while the @code{EXIT} statement in the middle loop ends that +loop but @emph{not} the outermost loop. + +@node Functions and Subroutines +@section Functions and Subroutines + +(The following information augments or overrides the information in +Chapter 15 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran +language. +Chapter 15 of that document otherwise serves as the basis +for the relevant aspects of GNU Fortran.) + +@menu +* %VAL():: +* %REF():: +* %DESCR():: +* Generics and Specifics:: +* REAL() and AIMAG() of Complex:: +* CMPLX() of DOUBLE PRECISION:: +* MIL-STD 1753:: +* f77/f2c Intrinsics:: +* Table of Intrinsic Functions:: +@end menu + +@node %VAL() +@subsection The @code{%VAL()} Construct +@cindex %VAL() construct + +@example +%VAL(@var{arg}) +@end example + +The @code{%VAL()} construct specifies that an argument, +@var{arg}, is to be passed by value, instead of by reference +or descriptor. + +@code{%VAL()} is restricted to actual arguments in +invocations of external procedures. + +Use of @code{%VAL()} is recommended only for code that +is accessing facilities outside of GNU Fortran, such as +operating system or windowing facilities. +It is best to constrain such uses to isolated portions of +a program---portions the deal specifically and exclusively +with low-level, system-dependent facilities. +Such portions might well provide a portable interface for +use by the program as a whole, but are themselves not +portable, and should be thoroughly tested each time they +are rebuilt using a new compiler or version of a compiler. + +@emph{Implementation Note:} Currently, @command{g77} passes +all arguments either by reference or by descriptor. + +Thus, use of @code{%VAL()} tends to be restricted to cases +where the called procedure is written in a language other +than Fortran that supports call-by-value semantics. +(C is an example of such a language.) + +@xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, +for detailed information on +how this particular version of @command{g77} passes arguments +to procedures. + +@node %REF() +@subsection The @code{%REF()} Construct +@cindex %REF() construct + +@example +%REF(@var{arg}) +@end example + +The @code{%REF()} construct specifies that an argument, +@var{arg}, is to be passed by reference, instead of by +value or descriptor. + +@code{%REF()} is restricted to actual arguments in +invocations of external procedures. + +Use of @code{%REF()} is recommended only for code that +is accessing facilities outside of GNU Fortran, such as +operating system or windowing facilities. +It is best to constrain such uses to isolated portions of +a program---portions the deal specifically and exclusively +with low-level, system-dependent facilities. +Such portions might well provide a portable interface for +use by the program as a whole, but are themselves not +portable, and should be thoroughly tested each time they +are rebuilt using a new compiler or version of a compiler. + +Do not depend on @code{%REF()} supplying a pointer to the +procedure being invoked. +While that is a likely implementation choice, other +implementation choices are available that preserve Fortran +pass-by-reference semantics without passing a pointer to +the argument, @var{arg}. +(For example, a copy-in/copy-out implementation.) + +@emph{Implementation Note:} Currently, @command{g77} passes +all arguments +(other than variables and arrays of type @code{CHARACTER}) +by reference. +Future versions of, or dialects supported by, @command{g77} might +not pass @code{CHARACTER} functions by reference. + +Thus, use of @code{%REF()} tends to be restricted to cases +where @var{arg} is type @code{CHARACTER} but the called +procedure accesses it via a means other than the method +used for Fortran @code{CHARACTER} arguments. + +@xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on +how this particular version of @command{g77} passes arguments +to procedures. + +@node %DESCR() +@subsection The @code{%DESCR()} Construct +@cindex %DESCR() construct + +@example +%DESCR(@var{arg}) +@end example + +The @code{%DESCR()} construct specifies that an argument, +@var{arg}, is to be passed by descriptor, instead of by +value or reference. + +@code{%DESCR()} is restricted to actual arguments in +invocations of external procedures. + +Use of @code{%DESCR()} is recommended only for code that +is accessing facilities outside of GNU Fortran, such as +operating system or windowing facilities. +It is best to constrain such uses to isolated portions of +a program---portions the deal specifically and exclusively +with low-level, system-dependent facilities. +Such portions might well provide a portable interface for +use by the program as a whole, but are themselves not +portable, and should be thoroughly tested each time they +are rebuilt using a new compiler or version of a compiler. + +Do not depend on @code{%DESCR()} supplying a pointer +and/or a length passed by value +to the procedure being invoked. +While that is a likely implementation choice, other +implementation choices are available that preserve the +pass-by-reference semantics without passing a pointer to +the argument, @var{arg}. +(For example, a copy-in/copy-out implementation.) +And, future versions of @command{g77} might change the +way descriptors are implemented, such as passing a +single argument pointing to a record containing the +pointer/length information instead of passing that same +information via two arguments as it currently does. + +@emph{Implementation Note:} Currently, @command{g77} passes +all variables and arrays of type @code{CHARACTER} +by descriptor. +Future versions of, or dialects supported by, @command{g77} might +pass @code{CHARACTER} functions by descriptor as well. + +Thus, use of @code{%DESCR()} tends to be restricted to cases +where @var{arg} is not type @code{CHARACTER} but the called +procedure accesses it via a means similar to the method +used for Fortran @code{CHARACTER} arguments. + +@xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on +how this particular version of @command{g77} passes arguments +to procedures. + +@node Generics and Specifics +@subsection Generics and Specifics +@cindex generic intrinsics +@cindex intrinsics, generic + +The ANSI FORTRAN 77 language defines generic and specific +intrinsics. +In short, the distinctions are: + +@itemize @bullet +@item +@emph{Specific} intrinsics have +specific types for their arguments and a specific return +type. + +@item +@emph{Generic} intrinsics are treated, +on a case-by-case basis in the program's source code, +as one of several possible specific intrinsics. + +Typically, a generic intrinsic has a return type that +is determined by the type of one or more of its arguments. +@end itemize + +The GNU Fortran language generalizes these concepts somewhat, +especially by providing intrinsic subroutines and generic +intrinsics that are treated as either a specific intrinsic subroutine +or a specific intrinsic function (e.g. @code{SECOND}). + +However, GNU Fortran avoids generalizing this concept to +the point where existing code would be accepted as meaning +something possibly different than what was intended. + +For example, @code{ABS} is a generic intrinsic, so all working +code written using @code{ABS} of an @code{INTEGER} argument +expects an @code{INTEGER} return value. +Similarly, all such code expects that @code{ABS} of an @code{INTEGER*2} +argument returns an @code{INTEGER*2} return value. + +Yet, @code{IABS} is a @emph{specific} intrinsic that accepts only +an @code{INTEGER(KIND=1)} argument. +Code that passes something other than an @code{INTEGER(KIND=1)} +argument to @code{IABS} is not valid GNU Fortran code, because +it is not clear what the author intended. + +For example, if @samp{J} is @code{INTEGER(KIND=6)}, @samp{IABS(J)} +is not defined by the GNU Fortran language, because the programmer +might have used that construct to mean any of the following, subtly +different, things: + +@itemize @bullet +@item +Convert @samp{J} to @code{INTEGER(KIND=1)} first +(as if @samp{IABS(INT(J))} had been written). + +@item +Convert the result of the intrinsic to @code{INTEGER(KIND=1)} +(as if @samp{INT(ABS(J))} had been written). + +@item +No conversion (as if @samp{ABS(J)} had been written). +@end itemize + +The distinctions matter especially when types and values wider than +@code{INTEGER(KIND=1)} (such as @code{INTEGER(KIND=2)}), or when +operations performing more ``arithmetic'' than absolute-value, are involved. + +The following sample program is not a valid GNU Fortran program, but +might be accepted by other compilers. +If so, the output is likely to be revealing in terms of how a given +compiler treats intrinsics (that normally are specific) when they +are given arguments that do not conform to their stated requirements: + +@cindex JCB002 program +@smallexample + PROGRAM JCB002 +C Version 1: +C Modified 1999-02-15 (Burley) to delete my email address. +C Modified 1997-05-21 (Burley) to accommodate compilers that implement +C INT(I1-I2) as INT(I1)-INT(I2) given INTEGER*2 I1,I2. +C +C Version 0: +C Written by James Craig Burley 1997-02-20. +C +C Purpose: +C Determine how compilers handle non-standard IDIM +C on INTEGER*2 operands, which presumably can be +C extrapolated into understanding how the compiler +C generally treats specific intrinsics that are passed +C arguments not of the correct types. +C +C If your compiler implements INTEGER*2 and INTEGER +C as the same type, change all INTEGER*2 below to +C INTEGER*1. +C + INTEGER*2 I0, I4 + INTEGER I1, I2, I3 + INTEGER*2 ISMALL, ILARGE + INTEGER*2 ITOOLG, ITWO + INTEGER*2 ITMP + LOGICAL L2, L3, L4 +C +C Find smallest INTEGER*2 number. +C + ISMALL=0 + 10 I0 = ISMALL-1 + IF ((I0 .GE. ISMALL) .OR. (I0+1 .NE. ISMALL)) GOTO 20 + ISMALL = I0 + GOTO 10 + 20 CONTINUE +C +C Find largest INTEGER*2 number. +C + ILARGE=0 + 30 I0 = ILARGE+1 + IF ((I0 .LE. ILARGE) .OR. (I0-1 .NE. ILARGE)) GOTO 40 + ILARGE = I0 + GOTO 30 + 40 CONTINUE +C +C Multiplying by two adds stress to the situation. +C + ITWO = 2 +C +C Need a number that, added to -2, is too wide to fit in I*2. +C + ITOOLG = ISMALL +C +C Use IDIM the straightforward way. +C + I1 = IDIM (ILARGE, ISMALL) * ITWO + ITOOLG +C +C Calculate result for first interpretation. +C + I2 = (INT (ILARGE) - INT (ISMALL)) * ITWO + ITOOLG +C +C Calculate result for second interpretation. +C + ITMP = ILARGE - ISMALL + I3 = (INT (ITMP)) * ITWO + ITOOLG +C +C Calculate result for third interpretation. +C + I4 = (ILARGE - ISMALL) * ITWO + ITOOLG +C +C Print results. +C + PRINT *, 'ILARGE=', ILARGE + PRINT *, 'ITWO=', ITWO + PRINT *, 'ITOOLG=', ITOOLG + PRINT *, 'ISMALL=', ISMALL + PRINT *, 'I1=', I1 + PRINT *, 'I2=', I2 + PRINT *, 'I3=', I3 + PRINT *, 'I4=', I4 + PRINT * + L2 = (I1 .EQ. I2) + L3 = (I1 .EQ. I3) + L4 = (I1 .EQ. I4) + IF (L2 .AND. .NOT.L3 .AND. .NOT.L4) THEN + PRINT *, 'Interp 1: IDIM(I*2,I*2) => IDIM(INT(I*2),INT(I*2))' + STOP + END IF + IF (L3 .AND. .NOT.L2 .AND. .NOT.L4) THEN + PRINT *, 'Interp 2: IDIM(I*2,I*2) => INT(DIM(I*2,I*2))' + STOP + END IF + IF (L4 .AND. .NOT.L2 .AND. .NOT.L3) THEN + PRINT *, 'Interp 3: IDIM(I*2,I*2) => DIM(I*2,I*2)' + STOP + END IF + PRINT *, 'Results need careful analysis.' + END +@end smallexample + +No future version of the GNU Fortran language +will likely permit specific intrinsic invocations with wrong-typed +arguments (such as @code{IDIM} in the above example), since +it has been determined that disagreements exist among +many production compilers on the interpretation of +such invocations. +These disagreements strongly suggest that Fortran programmers, +and certainly existing Fortran programs, disagree about the +meaning of such invocations. + +The first version of @code{JCB002} didn't accommodate some compilers' +treatment of @samp{INT(I1-I2)} where @samp{I1} and @samp{I2} are +@code{INTEGER*2}. +In such a case, these compilers apparently convert both +operands to @code{INTEGER*4} and then do an @code{INTEGER*4} subtraction, +instead of doing an @code{INTEGER*2} subtraction on the +original values in @samp{I1} and @samp{I2}. + +However, the results of the careful analyses done on the outputs +of programs compiled by these various compilers show that they +all implement either @samp{Interp 1} or @samp{Interp 2} above. + +Specifically, it is believed that the new version of @code{JCB002} +above will confirm that: + +@itemize @bullet +@item +Digital Semiconductor (``DEC'') Alpha OSF/1, HP-UX 10.0.1, AIX 3.2.5 +@command{f77} compilers all implement @samp{Interp 1}. + +@item +IRIX 5.3 @command{f77} compiler implements @samp{Interp 2}. + +@item +Solaris 2.5, SunOS 4.1.3, DECstation ULTRIX 4.3, +and IRIX 6.1 @command{f77} compilers all implement @samp{Interp 3}. +@end itemize + +If you get different results than the above for the stated +compilers, or have results for other compilers that might be +worth adding to the above list, please let us know the details +(compiler product, version, machine, results, and so on). + +@node REAL() and AIMAG() of Complex +@subsection @code{REAL()} and @code{AIMAG()} of Complex +@cindex @code{Real} intrinsic +@cindex intrinsics, @code{Real} +@cindex @code{AImag} intrinsic +@cindex intrinsics, @code{AImag} + +The GNU Fortran language disallows @code{REAL(@var{expr})} +and @code{AIMAG(@var{expr})}, +where @var{expr} is any @code{COMPLEX} type other than @code{COMPLEX(KIND=1)}, +except when they are used in the following way: + +@example +REAL(REAL(@var{expr})) +REAL(AIMAG(@var{expr})) +@end example + +@noindent +The above forms explicitly specify that the desired effect +is to convert the real or imaginary part of @var{expr}, which might +be some @code{REAL} type other than @code{REAL(KIND=1)}, +to type @code{REAL(KIND=1)}, +and have that serve as the value of the expression. + +The GNU Fortran language offers clearly named intrinsics to extract the +real and imaginary parts of a complex entity without any +conversion: + +@example +REALPART(@var{expr}) +IMAGPART(@var{expr}) +@end example + +To express the above using typical extended FORTRAN 77, +use the following constructs +(when @var{expr} is @code{COMPLEX(KIND=2)}): + +@example +DBLE(@var{expr}) +DIMAG(@var{expr}) +@end example + +The FORTRAN 77 language offers no way +to explicitly specify the real and imaginary parts of a complex expression of +arbitrary type, apparently as a result of requiring support for +only one @code{COMPLEX} type (@code{COMPLEX(KIND=1)}). +The concepts of converting an expression to type @code{REAL(KIND=1)} and +of extracting the real part of a complex expression were +thus ``smooshed'' by FORTRAN 77 into a single intrinsic, since +they happened to have the exact same effect in that language +(due to having only one @code{COMPLEX} type). + +@emph{Note:} When @option{-ff90} is in effect, +@command{g77} treats @samp{REAL(@var{expr})}, where @var{expr} is of +type @code{COMPLEX}, as @samp{REALPART(@var{expr})}, +whereas with @samp{-fugly-complex -fno-f90} in effect, it is +treated as @samp{REAL(REALPART(@var{expr}))}. + +@xref{Ugly Complex Part Extraction}, for more information. + +@node CMPLX() of DOUBLE PRECISION +@subsection @code{CMPLX()} of @code{DOUBLE PRECISION} +@cindex @code{Cmplx} intrinsic +@cindex intrinsics, @code{Cmplx} + +In accordance with Fortran 90 and at least some (perhaps all) +other compilers, the GNU Fortran language defines @code{CMPLX()} +as always returning a result that is type @code{COMPLEX(KIND=1)}. + +This means @samp{CMPLX(D1,D2)}, where @samp{D1} and @samp{D2} +are @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}), is treated as: + +@example +CMPLX(SNGL(D1), SNGL(D2)) +@end example + +(It was necessary for Fortran 90 to specify this behavior +for @code{DOUBLE PRECISION} arguments, since that is +the behavior mandated by FORTRAN 77.) + +The GNU Fortran language also provides the @code{DCMPLX()} intrinsic, +which is provided by some FORTRAN 77 compilers to construct +a @code{DOUBLE COMPLEX} entity from of @code{DOUBLE PRECISION} +operands. +However, this solution does not scale well when more @code{COMPLEX} types +(having various precisions and ranges) are offered by Fortran implementations. + +Fortran 90 extends the @code{CMPLX()} intrinsic by adding +an extra argument used to specify the desired kind of complex +result. +However, this solution is somewhat awkward to use, and +@command{g77} currently does not support it. + +The GNU Fortran language provides a simple way to build a complex +value out of two numbers, with the precise type of the value +determined by the types of the two numbers (via the usual +type-promotion mechanism): + +@example +COMPLEX(@var{real}, @var{imag}) +@end example + +When @var{real} and @var{imag} are the same @code{REAL} types, @code{COMPLEX()} +performs no conversion other than to put them together to form a +complex result of the same (complex version of real) type. + +@xref{Complex Intrinsic}, for more information. + +@node MIL-STD 1753 +@subsection MIL-STD 1753 Support +@cindex MIL-STD 1753 + +The GNU Fortran language includes the MIL-STD 1753 intrinsics +@code{BTEST}, @code{IAND}, @code{IBCLR}, @code{IBITS}, +@code{IBSET}, @code{IEOR}, @code{IOR}, @code{ISHFT}, +@code{ISHFTC}, @code{MVBITS}, and @code{NOT}. + +@node f77/f2c Intrinsics +@subsection @command{f77}/@command{f2c} Intrinsics + +The bit-manipulation intrinsics supported by traditional +@command{f77} and by @command{f2c} are available in the GNU Fortran language. +These include @code{AND}, @code{LSHIFT}, @code{OR}, @code{RSHIFT}, +and @code{XOR}. + +Also supported are the intrinsics @code{CDABS}, +@code{CDCOS}, @code{CDEXP}, @code{CDLOG}, @code{CDSIN}, +@code{CDSQRT}, @code{DCMPLX}, @code{DCONJG}, @code{DFLOAT}, +@code{DIMAG}, @code{DREAL}, and @code{IMAG}, +@code{ZABS}, @code{ZCOS}, @code{ZEXP}, @code{ZLOG}, @code{ZSIN}, +and @code{ZSQRT}. + +@node Table of Intrinsic Functions +@subsection Table of Intrinsic Functions +@cindex intrinsics, table of +@cindex table of intrinsics + +(Corresponds to Section 15.10 of ANSI X3.9-1978 FORTRAN 77.) + +The GNU Fortran language adds various functions, subroutines, types, +and arguments to the set of intrinsic functions in ANSI FORTRAN 77. +The complete set of intrinsics supported by the GNU Fortran language +is described below. + +Note that a name is not treated as that of an intrinsic if it is +specified in an @code{EXTERNAL} statement in the same program unit; +if a command-line option is used to disable the groups to which +the intrinsic belongs; or if the intrinsic is not named in an +@code{INTRINSIC} statement and a command-line option is used to +hide the groups to which the intrinsic belongs. + +So, it is recommended that any reference in a program unit to +an intrinsic procedure that is not a standard FORTRAN 77 +intrinsic be accompanied by an appropriate @code{INTRINSIC} +statement in that program unit. +This sort of defensive programming makes it more +likely that an implementation will issue a diagnostic rather +than generate incorrect code for such a reference. + +The terminology used below is based on that of the Fortran 90 +standard, so that the text may be more concise and accurate: + +@itemize @bullet +@item +@code{OPTIONAL} means the argument may be omitted. + +@item +@samp{A-1, A-2, @dots{}, A-n} means more than one argument +(generally named @samp{A}) may be specified. + +@item +@samp{scalar} means the argument must not be an array (must +be a variable or array element, or perhaps a constant if expressions +are permitted). + +@item +@samp{DIMENSION(4)} means the argument must be an array having 4 elements. + +@item +@code{INTENT(IN)} means the argument must be an expression +(such as a constant or a variable that is defined upon invocation +of the intrinsic). + +@item +@code{INTENT(OUT)} means the argument must be definable by the +invocation of the intrinsic (that is, must not be a constant nor +an expression involving operators other than array reference and +substring reference). + +@item +@code{INTENT(INOUT)} means the argument must be defined prior to, +and definable by, invocation of the intrinsic (a combination of +the requirements of @code{INTENT(IN)} and @code{INTENT(OUT)}. + +@item +@xref{Kind Notation}, for an explanation of @code{KIND}. +@end itemize + +@ifinfo +(Note that the empty lines appearing in the menu below +are not intentional---they result from a bug in the +GNU @command{makeinfo} program@dots{}a program that, if it +did not exist, would leave this document in far worse shape!) +@end ifinfo + +@c The actual documentation for intrinsics comes from +@c intdoc.texi, which in turn is automatically generated +@c from the internal g77 tables in intrin.def _and_ the +@c largely hand-written text in intdoc.h. So, if you want +@c to change or add to existing documentation on intrinsics, +@c you probably want to edit intdoc.h. +@c +@set familyF77 +@set familyGNU +@set familyASC +@set familyMIL +@set familyF90 +@clear familyVXT +@clear familyFVZ +@set familyF2C +@set familyF2U +@clear familyBADU77 +@include intdoc.texi + +@node Scope and Classes of Names +@section Scope and Classes of Symbolic Names +@cindex symbol names, scope and classes +@cindex scope + +(The following information augments or overrides the information in +Chapter 18 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran +language. +Chapter 18 of that document otherwise serves as the basis +for the relevant aspects of GNU Fortran.) + +@menu +* Underscores in Symbol Names:: +@end menu + +@node Underscores in Symbol Names +@subsection Underscores in Symbol Names +@cindex underscore + +Underscores (@samp{_}) are accepted in symbol names after the first +character (which must be a letter). + +@node I/O +@section I/O + +@cindex dollar sign +A dollar sign at the end of an output format specification suppresses +the newline at the end of the output. + +@cindex <> edit descriptor +@cindex edit descriptor, <> +Edit descriptors in @code{FORMAT} statements may contain compile-time +@code{INTEGER} constant expressions in angle brackets, such as +@smallexample +10 FORMAT (I<WIDTH>) +@end smallexample + +The @code{OPEN} specifier @code{NAME=} is equivalent to @code{FILE=}. + +These Fortran 90 features are supported: +@itemize @bullet +@item +@cindex FORMAT descriptors +@cindex Z edit descriptor +@cindex edit descriptor, Z +@cindex O edit descriptor +@cindex edit descriptor, O +The @code{O} and @code{Z} edit descriptors are supported for I/O of +integers in octal and hexadecimal formats, respectively. +@item +The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if +@code{STATUS='SCRATCH'} is supplied. The @code{STATUS='REPLACE'} +specifier is supported. +@end itemize + +@node Fortran 90 Features +@section Fortran 90 Features +@cindex Fortran 90 +@cindex extensions, from Fortran 90 + +For convenience this section collects a list (probably incomplete) of +the Fortran 90 features supported by the GNU Fortran language, even if +they are documented elsewhere. +@xref{Characters Lines Sequence,,@asis{Characters, Lines, and Execution Sequence}}, +for information on additional fixed source form lexical issues. +@cindex @option{-ffree-form} +Further, the free source form is supported through the +@option{-ffree-form} option. +@cindex @option{-ff90} +Other Fortran 90 features can be turned on by the @option{-ff90} option; +see @ref{Fortran 90}. +For information on the Fortran 90 intrinsics available, +see @ref{Table of Intrinsic Functions}. + +@table @asis +@item Automatic arrays in procedures +@item Character assignments +@cindex character assignments +In character assignments, the variable being assigned may occur on the +right hand side of the assignment. +@item Character strings +@cindex double quoted character constants +Strings may have zero length and substrings of character constants are +permitted. Character constants may be enclosed in double quotes +(@code{"}) as well as single quotes. @xref{Character Type}. +@item Construct names +(Symbolic tags on blocks.) @xref{Construct Names}. +@item @code{CYCLE} and @code{EXIT} +@xref{CYCLE and EXIT,,The @code{CYCLE} and @code{EXIT} Statements}. +@item @code{DOUBLE COMPLEX} +@xref{DOUBLE COMPLEX,,@code{DOUBLE COMPLEX} Statement}. +@item @code{DO WHILE} +@xref{DO WHILE}. +@item @code{END} decoration +@xref{Statements}. +@item @code{END DO} +@xref{END DO}. +@item @code{KIND} +@item @code{IMPLICIT NONE} +@item @code{INCLUDE} statements +@xref{INCLUDE}. +@item List-directed and namelist I/O on internal files +@item Binary, octal and hexadecimal constants +These are supported more generally than required by Fortran 90. +@xref{Integer Type}. +@item @samp{O} and @samp{Z} edit descriptors +@item @code{NAMELIST} +@xref{NAMELIST}. +@item @code{OPEN} specifiers +@code{STATUS='REPLACE'} is supported. +The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if +@code{STATUS='SCRATCH'} is supplied. +@item @code{FORMAT} edit descriptors +@cindex FORMAT descriptors +@cindex Z edit descriptor +@cindex edit descriptor, Z +The @code{Z} edit descriptor is supported. +@item Relational operators +The operators @code{<}, @code{<=}, @code{==}, @code{/=}, @code{>} and +@code{>=} may be used instead of @code{.LT.}, @code{.LE.}, @code{.EQ.}, +@code{.NE.}, @code{.GT.} and @code{.GE.} respectively. +@item @code{SELECT CASE} +Not fully implemented. +@xref{SELECT CASE on CHARACTER Type,, @code{SELECT CASE} on @code{CHARACTER} Type}. +@item Specification statements +A limited subset of the Fortran 90 syntax and semantics for variable +declarations is supported, including @code{KIND}. @xref{Kind Notation}. +(@code{KIND} is of limited usefulness in the absence of the +@code{KIND}-related intrinsics, since these intrinsics permit writing +more widely portable code.) An example of supported @code{KIND} usage +is: +@smallexample +INTEGER (KIND=1) :: FOO=1, BAR=2 +CHARACTER (LEN=3) FOO +@end smallexample +@code{PARAMETER} and @code{DIMENSION} attributes aren't supported. +@end table + +@node Other Dialects +@chapter Other Dialects + +GNU Fortran supports a variety of features that are not +considered part of the GNU Fortran language itself, but +are representative of various dialects of Fortran that +@command{g77} supports in whole or in part. + +Any of the features listed below might be disallowed by +@command{g77} unless some command-line option is specified. +Currently, some of the features are accepted using the +default invocation of @command{g77}, but that might change +in the future. + +@emph{Note: This portion of the documentation definitely needs a lot +of work!} + +@menu +* Source Form:: Details of fixed-form and free-form source. +* Trailing Comment:: Use of @samp{/*} to start a comment. +* Debug Line:: Use of @samp{D} in column 1. +* Dollar Signs:: Use of @samp{$} in symbolic names. +* Case Sensitivity:: Uppercase and lowercase in source files. +* VXT Fortran:: @dots{}versus the GNU Fortran language. +* Fortran 90:: @dots{}versus the GNU Fortran language. +* Pedantic Compilation:: Enforcing the standard. +* Distensions:: Misfeatures supported by GNU Fortran. +@end menu + +@node Source Form +@section Source Form +@cindex source file format +@cindex source format +@cindex file, source +@cindex source code +@cindex code, source +@cindex fixed form +@cindex free form + +GNU Fortran accepts programs written in either fixed form or +free form. + +Fixed form +corresponds to ANSI FORTRAN 77 (plus popular extensions, such as +allowing tabs) and Fortran 90's fixed form. + +Free form corresponds to +Fortran 90's free form (though possibly not entirely up-to-date, and +without complaining about some things that for which Fortran 90 requires +diagnostics, such as the spaces in the constant in @samp{R = 3 . 1}). + +The way a Fortran compiler views source files depends entirely on the +implementation choices made for the compiler, since those choices +are explicitly left to the implementation by the published Fortran +standards. +GNU Fortran currently tries to be somewhat like a few popular compilers +(@command{f2c}, Digital (``DEC'') Fortran, and so on). + +This section describes how @command{g77} interprets source lines. + +@menu +* Carriage Returns:: Carriage returns ignored. +* Tabs:: Tabs converted to spaces. +* Short Lines:: Short lines padded with spaces (fixed-form only). +* Long Lines:: Long lines truncated. +* Ampersands:: Special Continuation Lines. +@end menu + +@node Carriage Returns +@subsection Carriage Returns +@cindex carriage returns + +Carriage returns (@samp{\r}) in source lines are ignored. +This is somewhat different from @command{f2c}, which seems to treat them as +spaces outside character/Hollerith constants, and encodes them as @samp{\r} +inside such constants. + +@node Tabs +@subsection Tabs +@cindex tab character +@cindex horizontal tab + +A source line with a @key{TAB} character anywhere in it is treated as +entirely significant---however long it is---instead of ending in +column 72 (for fixed-form source) or 132 (for free-form source). +This also is different from @command{f2c}, which encodes tabs as +@samp{\t} (the ASCII @key{TAB} character) inside character +and Hollerith constants, but nevertheless seems to treat the column +position as if it had been affected by the canonical tab positioning. + +@command{g77} effectively +translates tabs to the appropriate number of spaces (a la the default +for the UNIX @command{expand} command) before doing any other processing, other +than (currently) noting whether a tab was found on a line and using this +information to decide how to interpret the length of the line and continued +constants. + +@node Short Lines +@subsection Short Lines +@cindex short source lines +@cindex space, padding with +@cindex source lines, short +@cindex lines, short + +Source lines shorter than the applicable fixed-form length are treated as +if they were padded with spaces to that length. +(None of this is relevant to source files written in free form.) + +This affects only +continued character and Hollerith constants, and is a different +interpretation than provided by some other popular compilers +(although a bit more consistent with the traditional punched-card +basis of Fortran and the way the Fortran standard expressed fixed +source form). + +@command{g77} might someday offer an option to warn about cases where differences +might be seen as a result of this treatment, and perhaps an option to +specify the alternate behavior as well. + +Note that this padding cannot apply to lines that are effectively of +infinite length---such lines are specified using command-line options +like @option{-ffixed-line-length-none}, for example. + +@node Long Lines +@subsection Long Lines +@cindex long source lines +@cindex truncation, of long lines +@cindex lines, long +@cindex source lines, long + +Source lines longer than the applicable length are truncated to that +length. +Currently, @command{g77} does not warn if the truncated characters are +not spaces, to accommodate existing code written for systems that +treated truncated text as commentary (especially in columns 73 through 80). + +@xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}, +for information on the @option{-ffixed-line-length-@var{n}} option, +which can be used to set the line length applicable to fixed-form +source files. + +@node Ampersands +@subsection Ampersand Continuation Line +@cindex ampersand continuation line +@cindex continuation line, ampersand + +A @samp{&} in column 1 of fixed-form source denotes an arbitrary-length +continuation line, imitating the behavior of @command{f2c}. + +@node Trailing Comment +@section Trailing Comment + +@cindex trailing comment +@cindex comment +@cindex characters, comment +@cindex /* +@cindex ! +@cindex exclamation point +@command{g77} supports use of @samp{/*} to start a trailing +comment. +In the GNU Fortran language, @samp{!} is used for this purpose. + +@samp{/*} is not in the GNU Fortran language +because the use of @samp{/*} in a program might +suggest to some readers that a block, not trailing, comment is +started (and thus ended by @samp{*/}, not end of line), +since that is the meaning of @samp{/*} in C. + +Also, such readers might think they can use @samp{//} to start +a trailing comment as an alternative to @samp{/*}, but +@samp{//} already denotes concatenation, and such a ``comment'' +might actually result in a program that compiles without +error (though it would likely behave incorrectly). + +@node Debug Line +@section Debug Line +@cindex debug line +@cindex comment line, debug + +Use of @samp{D} or @samp{d} as the first character (column 1) of +a source line denotes a debug line. + +In turn, a debug line is treated as either a comment line +or a normal line, depending on whether debug lines are enabled. + +When treated as a comment line, a line beginning with @samp{D} or +@samp{d} is treated as if it the first character was @samp{C} or @samp{c}, respectively. +When treated as a normal line, such a line is treated as if +the first character was @key{SPC} (space). + +(Currently, @command{g77} provides no means for treating debug +lines as normal lines.) + +@node Dollar Signs +@section Dollar Signs in Symbol Names +@cindex dollar sign +@cindex $ + +Dollar signs (@samp{$}) are allowed in symbol names (after the first character) +when the @option{-fdollar-ok} option is specified. + +@node Case Sensitivity +@section Case Sensitivity +@cindex case sensitivity +@cindex source file format +@cindex code, source +@cindex source code +@cindex uppercase letters +@cindex lowercase letters +@cindex letters, uppercase +@cindex letters, lowercase + +GNU Fortran offers the programmer way too much flexibility in deciding +how source files are to be treated vis-a-vis uppercase and lowercase +characters. +There are 66 useful settings that affect case sensitivity, plus 10 +settings that are nearly useless, with the remaining 116 settings +being either redundant or useless. + +None of these settings have any effect on the contents of comments +(the text after a @samp{c} or @samp{C} in Column 1, for example) +or of character or Hollerith constants. +Note that things like the @samp{E} in the statement +@samp{CALL FOO(3.2E10)} and the @samp{TO} in @samp{ASSIGN 10 TO LAB} +are considered built-in keywords, and so are affected by +these settings. + +Low-level switches are identified in this section as follows: + +@itemize @w{} +@item A +Source Case Conversion: + +@itemize @w{} +@item 0 +Preserve (see Note 1) +@item 1 +Convert to Upper Case +@item 2 +Convert to Lower Case +@end itemize + +@item B +Built-in Keyword Matching: + +@itemize @w{} +@item 0 +Match Any Case (per-character basis) +@item 1 +Match Upper Case Only +@item 2 +Match Lower Case Only +@item 3 +Match InitialCaps Only (see tables for spellings) +@end itemize + +@item C +Built-in Intrinsic Matching: + +@itemize @w{} +@item 0 +Match Any Case (per-character basis) +@item 1 +Match Upper Case Only +@item 2 +Match Lower Case Only +@item 3 +Match InitialCaps Only (see tables for spellings) +@end itemize + +@item D +User-defined Symbol Possibilities (warnings only): + +@itemize @w{} +@item 0 +Allow Any Case (per-character basis) +@item 1 +Allow Upper Case Only +@item 2 +Allow Lower Case Only +@item 3 +Allow InitialCaps Only (see Note 2) +@end itemize +@end itemize + +Note 1: @command{g77} eventually will support @code{NAMELIST} in a manner that is +consistent with these source switches---in the sense that input will be +expected to meet the same requirements as source code in terms +of matching symbol names and keywords (for the exponent letters). + +Currently, however, @code{NAMELIST} is supported by @code{libg2c}, +which uppercases @code{NAMELIST} input and symbol names for matching. +This means not only that @code{NAMELIST} output currently shows symbol +(and keyword) names in uppercase even if lower-case source +conversion (option A2) is selected, but that @code{NAMELIST} cannot be +adequately supported when source case preservation (option A0) +is selected. + +If A0 is selected, a warning message will be +output for each @code{NAMELIST} statement to this effect. +The behavior +of the program is undefined at run time if two or more symbol names +appear in a given @code{NAMELIST} such that the names are identical +when converted to upper case (e.g. @samp{NAMELIST /X/ VAR, Var, var}). +For complete and total elegance, perhaps there should be a warning +when option A2 is selected, since the output of NAMELIST is currently +in uppercase but will someday be lowercase (when a @code{libg77} is written), +but that seems to be overkill for a product in beta test. + +Note 2: Rules for InitialCaps names are: + +@itemize @minus +@item +Must be a single uppercase letter, @strong{or} +@item +Must start with an uppercase letter and contain at least one +lowercase letter. +@end itemize + +So @samp{A}, @samp{Ab}, @samp{ABc}, @samp{AbC}, and @samp{Abc} are +valid InitialCaps names, but @samp{AB}, @samp{A2}, and @samp{ABC} are +not. +Note that most, but not all, built-in names meet these +requirements---the exceptions are some of the two-letter format +specifiers, such as @code{BN} and @code{BZ}. + +Here are the names of the corresponding command-line options: + +@smallexample +A0: -fsource-case-preserve +A1: -fsource-case-upper +A2: -fsource-case-lower + +B0: -fmatch-case-any +B1: -fmatch-case-upper +B2: -fmatch-case-lower +B3: -fmatch-case-initcap + +C0: -fintrin-case-any +C1: -fintrin-case-upper +C2: -fintrin-case-lower +C3: -fintrin-case-initcap + +D0: -fsymbol-case-any +D1: -fsymbol-case-upper +D2: -fsymbol-case-lower +D3: -fsymbol-case-initcap +@end smallexample + +Useful combinations of the above settings, along with abbreviated +option names that set some of these combinations all at once: + +@smallexample + 1: A0-- B0--- C0--- D0--- -fcase-preserve + 2: A0-- B0--- C0--- D-1-- + 3: A0-- B0--- C0--- D--2- + 4: A0-- B0--- C0--- D---3 + 5: A0-- B0--- C-1-- D0--- + 6: A0-- B0--- C-1-- D-1-- + 7: A0-- B0--- C-1-- D--2- + 8: A0-- B0--- C-1-- D---3 + 9: A0-- B0--- C--2- D0--- +10: A0-- B0--- C--2- D-1-- +11: A0-- B0--- C--2- D--2- +12: A0-- B0--- C--2- D---3 +13: A0-- B0--- C---3 D0--- +14: A0-- B0--- C---3 D-1-- +15: A0-- B0--- C---3 D--2- +16: A0-- B0--- C---3 D---3 +17: A0-- B-1-- C0--- D0--- +18: A0-- B-1-- C0--- D-1-- +19: A0-- B-1-- C0--- D--2- +20: A0-- B-1-- C0--- D---3 +21: A0-- B-1-- C-1-- D0--- +22: A0-- B-1-- C-1-- D-1-- -fcase-strict-upper +23: A0-- B-1-- C-1-- D--2- +24: A0-- B-1-- C-1-- D---3 +25: A0-- B-1-- C--2- D0--- +26: A0-- B-1-- C--2- D-1-- +27: A0-- B-1-- C--2- D--2- +28: A0-- B-1-- C--2- D---3 +29: A0-- B-1-- C---3 D0--- +30: A0-- B-1-- C---3 D-1-- +31: A0-- B-1-- C---3 D--2- +32: A0-- B-1-- C---3 D---3 +33: A0-- B--2- C0--- D0--- +34: A0-- B--2- C0--- D-1-- +35: A0-- B--2- C0--- D--2- +36: A0-- B--2- C0--- D---3 +37: A0-- B--2- C-1-- D0--- +38: A0-- B--2- C-1-- D-1-- +39: A0-- B--2- C-1-- D--2- +40: A0-- B--2- C-1-- D---3 +41: A0-- B--2- C--2- D0--- +42: A0-- B--2- C--2- D-1-- +43: A0-- B--2- C--2- D--2- -fcase-strict-lower +44: A0-- B--2- C--2- D---3 +45: A0-- B--2- C---3 D0--- +46: A0-- B--2- C---3 D-1-- +47: A0-- B--2- C---3 D--2- +48: A0-- B--2- C---3 D---3 +49: A0-- B---3 C0--- D0--- +50: A0-- B---3 C0--- D-1-- +51: A0-- B---3 C0--- D--2- +52: A0-- B---3 C0--- D---3 +53: A0-- B---3 C-1-- D0--- +54: A0-- B---3 C-1-- D-1-- +55: A0-- B---3 C-1-- D--2- +56: A0-- B---3 C-1-- D---3 +57: A0-- B---3 C--2- D0--- +58: A0-- B---3 C--2- D-1-- +59: A0-- B---3 C--2- D--2- +60: A0-- B---3 C--2- D---3 +61: A0-- B---3 C---3 D0--- +62: A0-- B---3 C---3 D-1-- +63: A0-- B---3 C---3 D--2- +64: A0-- B---3 C---3 D---3 -fcase-initcap +65: A-1- B01-- C01-- D01-- -fcase-upper +66: A--2 B0-2- C0-2- D0-2- -fcase-lower +@end smallexample + +Number 22 is the ``strict'' ANSI FORTRAN 77 model wherein all input +(except comments, character constants, and Hollerith strings) must +be entered in uppercase. +Use @option{-fcase-strict-upper} to specify this +combination. + +Number 43 is like Number 22 except all input must be lowercase. Use +@option{-fcase-strict-lower} to specify this combination. + +Number 65 is the ``classic'' ANSI FORTRAN 77 model as implemented on many +non-UNIX machines whereby all the source is translated to uppercase. +Use @option{-fcase-upper} to specify this combination. + +Number 66 is the ``canonical'' UNIX model whereby all the source is +translated to lowercase. +Use @option{-fcase-lower} to specify this combination. + +There are a few nearly useless combinations: + +@smallexample +67: A-1- B01-- C01-- D--2- +68: A-1- B01-- C01-- D---3 +69: A-1- B01-- C--23 D01-- +70: A-1- B01-- C--23 D--2- +71: A-1- B01-- C--23 D---3 +72: A--2 B01-- C0-2- D-1-- +73: A--2 B01-- C0-2- D---3 +74: A--2 B01-- C-1-3 D0-2- +75: A--2 B01-- C-1-3 D-1-- +76: A--2 B01-- C-1-3 D---3 +@end smallexample + +The above allow some programs to be compiled but with restrictions that +make most useful programs impossible: Numbers 67 and 72 warn about +@emph{any} user-defined symbol names (such as @samp{SUBROUTINE FOO}); +Numbers +68 and 73 warn about any user-defined symbol names longer than one +character that don't have at least one non-alphabetic character after +the first; +Numbers 69 and 74 disallow any references to intrinsics; +and Numbers 70, 71, 75, and 76 are combinations of the restrictions in +67+69, 68+69, 72+74, and 73+74, respectively. + +All redundant combinations are shown in the above tables anyplace +where more than one setting is shown for a low-level switch. +For example, @samp{B0-2-} means either setting 0 or 2 is valid for switch B. +The ``proper'' setting in such a case is the one that copies the setting +of switch A---any other setting might slightly reduce the speed of +the compiler, though possibly to an unmeasurable extent. + +All remaining combinations are useless in that they prevent successful +compilation of non-null source files (source files with something other +than comments). + +@node VXT Fortran +@section VXT Fortran + +@cindex VXT extensions +@cindex extensions, VXT +@command{g77} supports certain constructs that +have different meanings in VXT Fortran than they +do in the GNU Fortran language. + +Generally, this manual uses the invented term VXT Fortran to refer +VAX FORTRAN (circa v4). +That compiler offered many popular features, though not necessarily +those that are specific to the VAX processor architecture, +the VMS operating system, +or Digital Equipment Corporation's Fortran product line. +(VAX and VMS probably are trademarks of Digital Equipment +Corporation.) + +An extension offered by a Digital Fortran product that also is +offered by several other Fortran products for different kinds of +systems is probably going to be considered for inclusion in @command{g77} +someday, and is considered a VXT Fortran feature. + +The @option{-fvxt} option generally specifies that, where +the meaning of a construct is ambiguous (means one thing +in GNU Fortran and another in VXT Fortran), the VXT Fortran +meaning is to be assumed. + +@menu +* Double Quote Meaning:: @samp{"2000} as octal constant. +* Exclamation Point:: @samp{!} in column 6. +@end menu + +@node Double Quote Meaning +@subsection Meaning of Double Quote +@cindex double quotes +@cindex character constants +@cindex constants, character +@cindex octal constants +@cindex constants, octal + +@command{g77} treats double-quote (@samp{"}) +as beginning an octal constant of @code{INTEGER(KIND=1)} type +when the @option{-fvxt} option is specified. +The form of this octal constant is + +@example +"@var{octal-digits} +@end example + +@noindent +where @var{octal-digits} is a nonempty string of characters in +the set @samp{01234567}. + +For example, the @option{-fvxt} option permits this: + +@example +PRINT *, "20 +END +@end example + +@noindent +The above program would print the value @samp{16}. + +@xref{Integer Type}, for information on the preferred construct +for integer constants specified using GNU Fortran's octal notation. + +(In the GNU Fortran language, the double-quote character (@samp{"}) +delimits a character constant just as does apostrophe (@samp{'}). +There is no way to allow +both constructs in the general case, since statements like +@samp{PRINT *,"2000 !comment?"} would be ambiguous.) + +@node Exclamation Point +@subsection Meaning of Exclamation Point in Column 6 +@cindex ! +@cindex exclamation point +@cindex continuation character +@cindex characters, continuation +@cindex comment character +@cindex characters, comment + +@command{g77} treats an exclamation point (@samp{!}) in column 6 of +a fixed-form source file +as a continuation character rather than +as the beginning of a comment +(as it does in any other column) +when the @option{-fvxt} option is specified. + +The following program, when run, prints a message indicating +whether it is interpreted according to GNU Fortran (and Fortran 90) +rules or VXT Fortran rules: + +@smallexample +C234567 (This line begins in column 1.) + I = 0 + !1 + IF (I.EQ.0) PRINT *, ' I am a VXT Fortran program' + IF (I.EQ.1) PRINT *, ' I am a Fortran 90 program' + IF (I.LT.0 .OR. I.GT.1) PRINT *, ' I am a HAL 9000 computer' + END +@end smallexample + +(In the GNU Fortran and Fortran 90 languages, exclamation point is +a valid character and, unlike space (@key{SPC}) or zero (@samp{0}), +marks a line as a continuation line when it appears in column 6.) + +@node Fortran 90 +@section Fortran 90 +@cindex compatibility, Fortran 90 +@cindex Fortran 90, compatibility + +The GNU Fortran language includes a number of features that are +part of Fortran 90, even when the @option{-ff90} option is not specified. +The features enabled by @option{-ff90} are intended to be those that, +when @option{-ff90} is not specified, would have another +meaning to @command{g77}---usually meaning something invalid in the +GNU Fortran language. + +So, the purpose of @option{-ff90} is not to specify whether @command{g77} is +to gratuitously reject Fortran 90 constructs. +The @option{-pedantic} option specified with @option{-fno-f90} is intended +to do that, although its implementation is certainly incomplete at +this point. + +When @option{-ff90} is specified: + +@itemize @bullet +@item +The type of @samp{REAL(@var{expr})} and @samp{AIMAG(@var{expr})}, +where @var{expr} is @code{COMPLEX} type, +is the same type as the real part of @var{expr}. + +For example, assuming @samp{Z} is type @code{COMPLEX(KIND=2)}, +@samp{REAL(Z)} would return a value of type @code{REAL(KIND=2)}, +not of type @code{REAL(KIND=1)}, since @option{-ff90} is specified. +@end itemize + +@node Pedantic Compilation +@section Pedantic Compilation +@cindex pedantic compilation +@cindex compilation, pedantic + +The @option{-fpedantic} command-line option specifies that @command{g77} +is to warn about code that is not standard-conforming. +This is useful for finding +some extensions @command{g77} accepts that other compilers might not accept. +(Note that the @option{-pedantic} and @option{-pedantic-errors} options +always imply @option{-fpedantic}.) + +With @option{-fno-f90} in force, ANSI FORTRAN 77 is used as the standard +for conforming code. +With @option{-ff90} in force, Fortran 90 is used. + +The constructs for which @command{g77} issues diagnostics when @option{-fpedantic} +and @option{-fno-f90} are in force are: + +@itemize @bullet +@item +Automatic arrays, as in + +@example +SUBROUTINE X(N) +REAL A(N) +@dots{} +@end example + +@noindent +where @samp{A} is not listed in any @code{ENTRY} statement, +and thus is not a dummy argument. + +@item +The commas in @samp{READ (5), I} and @samp{WRITE (10), J}. + +These commas are disallowed by FORTRAN 77, but, while strictly +superfluous, are syntactically elegant, +especially given that commas are required in statements such +as @samp{READ 99, I} and @samp{PRINT *, J}. +Many compilers permit the superfluous commas for this reason. + +@item +@code{DOUBLE COMPLEX}, either explicitly or implicitly. + +An explicit use of this type is via a @code{DOUBLE COMPLEX} or +@code{IMPLICIT DOUBLE COMPLEX} statement, for examples. + +An example of an implicit use is the expression @samp{C*D}, +where @samp{C} is @code{COMPLEX(KIND=1)} +and @samp{D} is @code{DOUBLE PRECISION}. +This expression is prohibited by ANSI FORTRAN 77 +because the rules of promotion would suggest that it +produce a @code{DOUBLE COMPLEX} result---a type not +provided for by that standard. + +@item +Automatic conversion of numeric +expressions to @code{INTEGER(KIND=1)} in contexts such as: + +@itemize @minus +@item +Array-reference indexes. +@item +Alternate-return values. +@item +Computed @code{GOTO}. +@item +@code{FORMAT} run-time expressions (not yet supported). +@item +Dimension lists in specification statements. +@item +Numbers for I/O statements (such as @samp{READ (UNIT=3.2), I}) +@item +Sizes of @code{CHARACTER} entities in specification statements. +@item +Kind types in specification entities (a Fortran 90 feature). +@item +Initial, terminal, and incrementation parameters for implied-@code{DO} +constructs in @code{DATA} statements. +@end itemize + +@item +Automatic conversion of @code{LOGICAL} expressions to @code{INTEGER} +in contexts such as arithmetic @code{IF} (where @code{COMPLEX} +expressions are disallowed anyway). + +@item +Zero-size array dimensions, as in: + +@example +INTEGER I(10,20,4:2) +@end example + +@item +Zero-length @code{CHARACTER} entities, as in: + +@example +PRINT *, '' +@end example + +@item +Substring operators applied to character constants and named +constants, as in: + +@example +PRINT *, 'hello'(3:5) +@end example + +@item +Null arguments passed to statement function, as in: + +@example +PRINT *, FOO(,3) +@end example + +@item +Disagreement among program units regarding whether a given @code{COMMON} +area is @code{SAVE}d (for targets where program units in a single source +file are ``glued'' together as they typically are for UNIX development +environments). + +@item +Disagreement among program units regarding the size of a +named @code{COMMON} block. + +@item +Specification statements following first @code{DATA} statement. + +(In the GNU Fortran language, @samp{DATA I/1/} may be followed by @samp{INTEGER J}, +but not @samp{INTEGER I}. +The @option{-fpedantic} option disallows both of these.) + +@item +Semicolon as statement separator, as in: + +@example +CALL FOO; CALL BAR +@end example +@c +@c @item +@c Comma before list of I/O items in @code{WRITE} +@c @c, @code{ENCODE}, @code{DECODE}, and @code{REWRITE} +@c statements, as with @code{READ} (as explained above). + +@item +Use of @samp{&} in column 1 of fixed-form source (to indicate continuation). + +@item +Use of @code{CHARACTER} constants to initialize numeric entities, and vice +versa. + +@item +Expressions having two arithmetic operators in a row, such +as @samp{X*-Y}. +@end itemize + +If @option{-fpedantic} is specified along with @option{-ff90}, the +following constructs result in diagnostics: + +@itemize @bullet +@item +Use of semicolon as a statement separator on a line +that has an @code{INCLUDE} directive. +@end itemize + +@node Distensions +@section Distensions +@cindex distensions +@cindex ugly features +@cindex features, ugly + +The @option{-fugly-*} command-line options determine whether certain +features supported by VAX FORTRAN and other such compilers, but considered +too ugly to be in code that can be changed to use safer and/or more +portable constructs, are accepted. +These are humorously referred to as ``distensions'', +extensions that just plain look ugly in the harsh light of day. + +@menu +* Ugly Implicit Argument Conversion:: Disabled via @option{-fno-ugly-args}. +* Ugly Assumed-Size Arrays:: Enabled via @option{-fugly-assumed}. +* Ugly Null Arguments:: Enabled via @option{-fugly-comma}. +* Ugly Complex Part Extraction:: Enabled via @option{-fugly-complex}. +* Ugly Conversion of Initializers:: Disabled via @option{-fno-ugly-init}. +* Ugly Integer Conversions:: Enabled via @option{-fugly-logint}. +* Ugly Assigned Labels:: Enabled via @option{-fugly-assign}. +@end menu + +@node Ugly Implicit Argument Conversion +@subsection Implicit Argument Conversion +@cindex Hollerith constants +@cindex constants, Hollerith + +The @option{-fno-ugly-args} option disables +passing typeless and Hollerith constants as actual arguments +in procedure invocations. +For example: + +@example +CALL FOO(4HABCD) +CALL BAR('123'O) +@end example + +@noindent +These constructs can be too easily used to create non-portable +code, but are not considered as ``ugly'' as others. +Further, they are widely used in existing Fortran source code +in ways that often are quite portable. +Therefore, they are enabled by default. + +@node Ugly Assumed-Size Arrays +@subsection Ugly Assumed-Size Arrays +@cindex arrays, assumed-size +@cindex assumed-size arrays +@cindex DIMENSION X(1) + +The @option{-fugly-assumed} option enables +the treatment of any array with a final dimension specified as @samp{1} +as an assumed-size array, as if @samp{*} had been specified +instead. + +For example, @samp{DIMENSION X(1)} is treated as if it +had read @samp{DIMENSION X(*)} if @samp{X} is listed as +a dummy argument in a preceding @code{SUBROUTINE}, @code{FUNCTION}, +or @code{ENTRY} statement in the same program unit. + +Use an explicit lower bound to avoid this interpretation. +For example, @samp{DIMENSION X(1:1)} is never treated as if +it had read @samp{DIMENSION X(*)} or @samp{DIMENSION X(1:*)}. +Nor is @samp{DIMENSION X(2-1)} affected by this option, +since that kind of expression is unlikely to have been +intended to designate an assumed-size array. + +This option is used to prevent warnings being issued about apparent +out-of-bounds reference such as @samp{X(2) = 99}. + +It also prevents the array from being used in contexts that +disallow assumed-size arrays, such as @samp{PRINT *,X}. +In such cases, a diagnostic is generated and the source file is +not compiled. + +The construct affected by this option is used only in old code +that pre-exists the widespread acceptance of adjustable and assumed-size +arrays in the Fortran community. + +@emph{Note:} This option does not affect how @samp{DIMENSION X(1)} is +treated if @samp{X} is listed as a dummy argument only +@emph{after} the @code{DIMENSION} statement (presumably in +an @code{ENTRY} statement). +For example, @option{-fugly-assumed} has no effect on the +following program unit: + +@example +SUBROUTINE X +REAL A(1) +RETURN +ENTRY Y(A) +PRINT *, A +END +@end example + +@node Ugly Complex Part Extraction +@subsection Ugly Complex Part Extraction +@cindex complex values +@cindex real part +@cindex imaginary part + +The @option{-fugly-complex} option enables +use of the @code{REAL()} and @code{AIMAG()} +intrinsics with arguments that are +@code{COMPLEX} types other than @code{COMPLEX(KIND=1)}. + +With @option{-ff90} in effect, these intrinsics return +the unconverted real and imaginary parts (respectively) +of their argument. + +With @option{-fno-f90} in effect, these intrinsics convert +the real and imaginary parts to @code{REAL(KIND=1)}, and return +the result of that conversion. + +Due to this ambiguity, the GNU Fortran language defines +these constructs as invalid, except in the specific +case where they are entirely and solely passed as an +argument to an invocation of the @code{REAL()} intrinsic. +For example, + +@example +REAL(REAL(Z)) +@end example + +@noindent +is permitted even when @samp{Z} is @code{COMPLEX(KIND=2)} +and @option{-fno-ugly-complex} is in effect, because the +meaning is clear. + +@command{g77} enforces this restriction, unless @option{-fugly-complex} +is specified, in which case the appropriate interpretation is +chosen and no diagnostic is issued. + +@xref{CMPAMBIG}, for information on how to cope with existing +code with unclear expectations of @code{REAL()} and @code{AIMAG()} +with @code{COMPLEX(KIND=2)} arguments. + +@xref{RealPart Intrinsic}, for information on the @code{REALPART()} +intrinsic, used to extract the real part of a complex expression +without conversion. +@xref{ImagPart Intrinsic}, for information on the @code{IMAGPART()} +intrinsic, used to extract the imaginary part of a complex expression +without conversion. + +@node Ugly Null Arguments +@subsection Ugly Null Arguments +@cindex trailing comma +@cindex comma, trailing +@cindex characters, comma +@cindex null arguments +@cindex arguments, null + +The @option{-fugly-comma} option enables use of a single trailing comma +to mean ``pass an extra trailing null argument'' +in a list of actual arguments to an external procedure, +and use of an empty list of arguments to such a procedure +to mean ``pass a single null argument''. + +@cindex omitting arguments +@cindex arguments, omitting +(Null arguments often are used in some procedure-calling +schemes to indicate omitted arguments.) + +For example, @samp{CALL FOO(,)} means ``pass +two null arguments'', rather than ``pass one null argument''. +Also, @samp{CALL BAR()} means ``pass one null argument''. + +This construct is considered ``ugly'' because it does not +provide an elegant way to pass a single null argument +that is syntactically distinct from passing no arguments. +That is, this construct changes the meaning of code that +makes no use of the construct. + +So, with @option{-fugly-comma} in force, @samp{CALL FOO()} +and @samp{I = JFUNC()} pass a single null argument, instead +of passing no arguments as required by the Fortran 77 and +90 standards. + +@emph{Note:} Many systems gracefully allow the case +where a procedure call passes one extra argument that the +called procedure does not expect. + +So, in practice, there might be no difference in +the behavior of a program that does @samp{CALL FOO()} +or @samp{I = JFUNC()} and is compiled with @option{-fugly-comma} +in force as compared to its behavior when compiled +with the default, @option{-fno-ugly-comma}, in force, +assuming @samp{FOO} and @samp{JFUNC} do not expect any +arguments to be passed. + +@node Ugly Conversion of Initializers +@subsection Ugly Conversion of Initializers + +The constructs disabled by @option{-fno-ugly-init} are: + +@itemize @bullet +@cindex Hollerith constants +@cindex constants, Hollerith +@item +Use of Hollerith and typeless constants in contexts where they set +initial (compile-time) values for variables, arrays, and named +constants---that is, @code{DATA} and @code{PARAMETER} statements, plus +type-declaration statements specifying initial values. + +Here are some sample initializations that are disabled by the +@option{-fno-ugly-init} option: + +@example +PARAMETER (VAL='9A304FFE'X) +REAL*8 STRING/8HOUTPUT00/ +DATA VAR/4HABCD/ +@end example + +@cindex character constants +@cindex constants, character +@item +In the same contexts as above, use of character constants to initialize +numeric items and vice versa (one constant per item). + +Here are more sample initializations that are disabled by the +@option{-fno-ugly-init} option: + +@example +INTEGER IA +CHARACTER BELL +PARAMETER (IA = 'A') +PARAMETER (BELL = 7) +@end example + +@item +Use of Hollerith and typeless constants on the right-hand side +of assignment statements to numeric types, and in other +contexts (such as passing arguments in invocations of +intrinsic procedures and statement functions) that +are treated as assignments to known types (the dummy +arguments, in these cases). + +Here are sample statements that are disabled by the +@option{-fno-ugly-init} option: + +@example +IVAR = 4HABCD +PRINT *, IMAX0(2HAB, 2HBA) +@end example +@end itemize + +The above constructs, when used, +can tend to result in non-portable code. +But, they are widely used in existing Fortran code in ways +that often are quite portable. +Therefore, they are enabled by default. + +@node Ugly Integer Conversions +@subsection Ugly Integer Conversions + +The constructs enabled via @option{-fugly-logint} are: + +@itemize @bullet +@item +Automatic conversion between @code{INTEGER} and @code{LOGICAL} as +dictated by +context (typically implies nonportable dependencies on how a +particular implementation encodes @code{.TRUE.} and @code{.FALSE.}). + +@item +Use of a @code{LOGICAL} variable in @code{ASSIGN} and assigned-@code{GOTO} +statements. +@end itemize + +The above constructs are disabled by default because use +of them tends to lead to non-portable code. +Even existing Fortran code that uses that often turns out +to be non-portable, if not outright buggy. + +Some of this is due to differences among implementations as +far as how @code{.TRUE.} and @code{.FALSE.} are encoded as +@code{INTEGER} values---Fortran code that assumes a particular +coding is likely to use one of the above constructs, and is +also likely to not work correctly on implementations using +different encodings. + +@xref{Equivalence Versus Equality}, for more information. + +@node Ugly Assigned Labels +@subsection Ugly Assigned Labels +@cindex ASSIGN statement +@cindex statements, ASSIGN +@cindex assigned labels +@cindex pointers + +The @option{-fugly-assign} option forces @command{g77} to use the +same storage for assigned labels as it would for a normal +assignment to the same variable. + +For example, consider the following code fragment: + +@example +I = 3 +ASSIGN 10 TO I +@end example + +@noindent +Normally, for portability and improved diagnostics, @command{g77} +reserves distinct storage for a ``sibling'' of @samp{I}, used +only for @code{ASSIGN} statements to that variable (along with +the corresponding assigned-@code{GOTO} and assigned-@code{FORMAT}-I/O +statements that reference the variable). + +However, some code (that violates the ANSI FORTRAN 77 standard) +attempts to copy assigned labels among variables involved with +@code{ASSIGN} statements, as in: + +@example +ASSIGN 10 TO I +ISTATE(5) = I +@dots{} +J = ISTATE(ICUR) +GOTO J +@end example + +@noindent +Such code doesn't work under @command{g77} unless @option{-fugly-assign} +is specified on the command-line, ensuring that the value of @code{I} +referenced in the second line is whatever value @command{g77} uses +to designate statement label @samp{10}, so the value may be +copied into the @samp{ISTATE} array, later retrieved into a +variable of the appropriate type (@samp{J}), and used as the target of +an assigned-@code{GOTO} statement. + +@emph{Note:} To avoid subtle program bugs, +when @option{-fugly-assign} is specified, +@command{g77} requires the type of variables +specified in assigned-label contexts +@emph{must} be the same type returned by @code{%LOC()}. +On many systems, this type is effectively the same +as @code{INTEGER(KIND=1)}, while, on others, it is +effectively the same as @code{INTEGER(KIND=2)}. + +Do @emph{not} depend on @command{g77} actually writing valid pointers +to these variables, however. +While @command{g77} currently chooses that implementation, it might +be changed in the future. + +@xref{Assigned Statement Labels,,Assigned Statement Labels (ASSIGN and GOTO)}, +for implementation details on assigned-statement labels. + +@node Compiler +@chapter The GNU Fortran Compiler + +The GNU Fortran compiler, @command{g77}, supports programs written +in the GNU Fortran language and in some other dialects of Fortran. + +Some aspects of how @command{g77} works are universal regardless +of dialect, and yet are not properly part of the GNU Fortran +language itself. +These are described below. + +@emph{Note: This portion of the documentation definitely needs a lot +of work!} + +@menu +* Compiler Limits:: +* Run-time Environment Limits:: +* Compiler Types:: +* Compiler Constants:: +* Compiler Intrinsics:: +@end menu + +@node Compiler Limits +@section Compiler Limits +@cindex limits, compiler +@cindex compiler limits + +@command{g77}, as with GNU tools in general, imposes few arbitrary restrictions +on lengths of identifiers, number of continuation lines, number of external +symbols in a program, and so on. + +@cindex options, -Nl +@cindex -Nl option +@cindex options, -Nx +@cindex -Nx option +@cindex limits, continuation lines +@cindex limits, lengths of names +For example, some other Fortran compiler have an option +(such as @option{-Nl@var{x}}) to increase the limit on the +number of continuation lines. +Also, some Fortran compilation systems have an option +(such as @option{-Nx@var{x}}) to increase the limit on the +number of external symbols. + +@command{g77}, @command{gcc}, and GNU @command{ld} (the GNU linker) have +no equivalent options, since they do not impose arbitrary +limits in these areas. + +@cindex rank, maximum +@cindex maximum rank +@cindex number of dimensions, maximum +@cindex maximum number of dimensions +@cindex limits, rank +@cindex limits, array dimensions +@command{g77} does currently limit the number of dimensions in an array +to the same degree as do the Fortran standards---seven (7). +This restriction might be lifted in a future version. + +@node Run-time Environment Limits +@section Run-time Environment Limits +@cindex limits, run-time library +@cindex wraparound + +As a portable Fortran implementation, +@command{g77} offers its users direct access to, +and otherwise depends upon, +the underlying facilities of the system +used to build @command{g77}, +the system on which @command{g77} itself is used to compile programs, +and the system on which the @command{g77}-compiled program is actually run. +(For most users, the three systems are of the same +type---combination of operating environment and hardware---often +the same physical system.) + +The run-time environment for a particular system +inevitably imposes some limits on a program's use +of various system facilities. +These limits vary from system to system. + +Even when such limits might be well beyond the +possibility of being encountered on a particular system, +the @command{g77} run-time environment +has certain built-in limits, +usually, but not always, stemming from intrinsics +with inherently limited interfaces. + +Currently, the @command{g77} run-time environment +does not generally offer a less-limiting environment +by augmenting the underlying system's own environment. + +Therefore, code written in the GNU Fortran language, +while syntactically and semantically portable, +might nevertheless make non-portable assumptions +about the run-time environment---assumptions that +prove to be false for some particular environments. + +The GNU Fortran language, +the @command{g77} compiler and run-time environment, +and the @command{g77} documentation +do not yet offer comprehensive portable work-arounds for such limits, +though programmers should be able to +find their own in specific instances. + +Not all of the limitations are described in this document. +Some of the known limitations include: + +@menu +* Timer Wraparounds:: +* Year 2000 (Y2K) Problems:: +* Array Size:: +* Character-variable Length:: +* Year 10000 (Y10K) Problems:: +@end menu + +@node Timer Wraparounds +@subsection Timer Wraparounds + +Intrinsics that return values computed from system timers, +whether elapsed (wall-clock) timers, +process CPU timers, +or other kinds of timers, +are prone to experiencing wrap-around errors +(or returning wrapped-around values from successive calls) +due to insufficient ranges +offered by the underlying system's timers. + +@cindex negative time +@cindex short time +@cindex long time +Some of the symptoms of such behaviors include +apparently negative time being computed for a duration, +an extremely short amount of time being computed for a long duration, +and an extremely long amount of time being computed for a short duration. + +See the following for intrinsics +known to have potential problems in these areas +on at least some systems: +@ref{CPU_Time Intrinsic}, +@ref{DTime Intrinsic (function)}, @ref{DTime Intrinsic (subroutine)}, +@ref{ETime Intrinsic (function)}, @ref{ETime Intrinsic (subroutine)}, +@ref{MClock Intrinsic}, @ref{MClock8 Intrinsic}, +@ref{Secnds Intrinsic}, +@ref{Second Intrinsic (function)}, @ref{Second Intrinsic (subroutine)}, +@ref{System_Clock Intrinsic}, +@ref{Time Intrinsic (UNIX)}, @ref{Time Intrinsic (VXT)}, +@ref{Time8 Intrinsic}. + +@node Year 2000 (Y2K) Problems +@subsection Year 2000 (Y2K) Problems +@cindex Y2K compliance +@cindex Year 2000 compliance + +While the @command{g77} compiler itself is believed to +be Year-2000 (Y2K) compliant, +some intrinsics are not, +and, potentially, some underlying systems are not, +perhaps rendering some Y2K-compliant intrinsics +non-compliant when used on those particular systems. + +Fortran code that uses non-Y2K-compliant intrinsics +(listed below) +is, itself, almost certainly not compliant, +and should be modified to use Y2K-compliant intrinsics instead. + +Fortran code that uses no non-Y2K-compliant intrinsics, +but which currently is running on a non-Y2K-compliant system, +can be made more Y2K compliant by compiling and +linking it for use on a new Y2K-compliant system, +such as a new version of an old, non-Y2K-compliant, system. + +Currently, information on Y2K and related issues +is being maintained at +@uref{http://www.gnu.org/software/year2000-list.html}. + +See the following for intrinsics +known to have potential problems in these areas +on at least some systems: +@ref{Date Intrinsic}, +@ref{IDate Intrinsic (VXT)}. + +@cindex y2kbuggy +@cindex date_y2kbuggy_0 +@cindex vxtidate_y2kbuggy_0 +@cindex G77_date_y2kbuggy_0 +@cindex G77_vxtidate_y2kbuggy_0 +The @code{libg2c} library +shipped with any @command{g77} that warns +about invocation of a non-Y2K-compliant intrinsic +has renamed the @code{EXTERNAL} procedure names +of those intrinsics. +This is done so that +the @code{libg2c} implementations of these intrinsics +cannot be directly linked to +as @code{EXTERNAL} names +(which normally would avoid the non-Y2K-intrinsic warning). + +The renamed forms of the @code{EXTERNAL} names +of these renamed procedures +may be linked to +by appending the string @samp{_y2kbug} +to the name of the procedure +in the source code. +For example: + +@smallexample +CHARACTER*20 STR +INTEGER YY, MM, DD +EXTERNAL DATE_Y2KBUG, VXTIDATE_Y2KBUG +CALL DATE_Y2KBUG (STR) +CALL VXTIDATE_Y2KBUG (MM, DD, YY) +@end smallexample + +(Note that the @code{EXTERNAL} statement +is not actually required, +since the modified names are not recognized as intrinsics +by the current version of @command{g77}. +But it is shown in this specific case, +for purposes of illustration.) + +The renaming of @code{EXTERNAL} procedure names of these intrinsics +causes unresolved references at link time. +For example, @samp{EXTERNAL DATE; CALL DATE(STR)} +is normally compiled by @command{g77} +as, in C, @samp{date_(&str, 20);}. +This, in turn, links to the @code{date_} procedure +in the @code{libE77} portion of @code{libg2c}, +which purposely calls a nonexistent procedure +named @code{G77_date_y2kbuggy_0}. +The resulting link-time error is designed, via this name, +to encourage the programmer to look up the +index entries to this portion of the @command{g77} documentation. + +Generally, we recommend that the @code{EXTERNAL} method +of invoking procedures in @code{libg2c} +@emph{not} be used. +When used, some of the correctness checking +normally performed by @command{g77} +is skipped. + +In particular, it is probably better to use the +@code{INTRINSIC} method of invoking +non-Y2K-compliant procedures, +so anyone compiling the code +can quickly notice the potential Y2K problems +(via the warnings printing by @command{g77}) +without having to even look at the code itself. + +If there are problems linking @code{libg2c} +to code compiled by @command{g77} +that involve the string @samp{y2kbug}, +and these are not explained above, +that probably indicates +that a version of @code{libg2c} +older than @command{g77} +is being linked to, +or that the new library is being linked +to code compiled by an older version of @command{g77}. + +That's because, as of the version that warns about +non-Y2K-compliant intrinsic invocation, +@command{g77} references the @code{libg2c} implementations +of those intrinsics +using new names, containing the string @samp{y2kbug}. + +So, linking newly-compiled code +(invoking one of the intrinsics in question) +to an old library +might yield an unresolved reference +to @code{G77_date_y2kbug_0}. +(The old library calls it @code{G77_date_0}.) + +Similarly, linking previously-compiled code +to a new library +might yield an unresolved reference +to @code{G77_vxtidate_0}. +(The new library calls it @code{G77_vxtidate_y2kbug_0}.) + +The proper fix for the above problems +is to obtain the latest release of @command{g77} +and related products +(including @code{libg2c}) +and install them on all systems, +then recompile, relink, and install +(as appropriate) +all existing Fortran programs. + +(Normally, this sort of renaming is steadfastly avoided. +In this case, however, it seems more important to highlight +potential Y2K problems +than to ease the transition +of potentially non-Y2K-compliant code +to new versions of @command{g77} and @code{libg2c}.) + +@node Array Size +@subsection Array Size +@cindex limits, array size +@cindex array size + +Currently, @command{g77} uses the default @code{INTEGER} type +for array indexes, +which limits the sizes of single-dimension arrays +on systems offering a larger address space +than can be addressed by that type. +(That @command{g77} puts all arrays in memory +could be considered another limitation---it +could use large temporary files---but that decision +is left to the programmer as an implementation choice +by most Fortran implementations.) + +@c ??? Investigate this, to offer a more clear statement +@c than the following paragraphs do. -- burley 1999-02-17 +It is not yet clear whether this limitation +never, sometimes, or always applies to the +sizes of multiple-dimension arrays as a whole. + +For example, on a system with 64-bit addresses +and 32-bit default @code{INTEGER}, +an array with a size greater than can be addressed +by a 32-bit offset +can be declared using multiple dimensions. +Such an array is therefore larger +than a single-dimension array can be, +on the same system. + +@cindex limits, multi-dimension arrays +@cindex multi-dimension arrays +@cindex arrays, dimensioning +Whether large multiple-dimension arrays are reliably supported +depends mostly on the @command{gcc} back end (code generator) +used by @command{g77}, and has not yet been fully investigated. + +@node Character-variable Length +@subsection Character-variable Length +@cindex limits, on character-variable length +@cindex character-variable length + +Currently, @command{g77} uses the default @code{INTEGER} type +for the lengths of @code{CHARACTER} variables +and array elements. + +This means that, for example, +a system with a 64-bit address space +and a 32-bit default @code{INTEGER} type +does not, under @command{g77}, +support a @code{CHARACTER*@var{n}} declaration +where @var{n} is greater than 2147483647. + +@node Year 10000 (Y10K) Problems +@subsection Year 10000 (Y10K) Problems +@cindex Y10K compliance +@cindex Year 10000 compliance + +Most intrinsics returning, or computing values based on, +date information are prone to Year-10000 (Y10K) problems, +due to supporting only 4 digits for the year. + +See the following for examples: +@ref{FDate Intrinsic (function)}, @ref{FDate Intrinsic (subroutine)}, +@ref{IDate Intrinsic (UNIX)}, +@ref{Time Intrinsic (VXT)}, +@ref{Date_and_Time Intrinsic}. + +@node Compiler Types +@section Compiler Types +@cindex types, of data +@cindex data types + +Fortran implementations have a fair amount of freedom given them by the +standard as far as how much storage space is used and how much precision +and range is offered by the various types such as @code{LOGICAL(KIND=1)}, +@code{INTEGER(KIND=1)}, @code{REAL(KIND=1)}, @code{REAL(KIND=2)}, +@code{COMPLEX(KIND=1)}, and @code{CHARACTER}. +Further, many compilers offer so-called @samp{*@var{n}} notation, but +the interpretation of @var{n} varies across compilers and target architectures. + +The standard requires that @code{LOGICAL(KIND=1)}, @code{INTEGER(KIND=1)}, +and @code{REAL(KIND=1)} +occupy the same amount of storage space, and that @code{COMPLEX(KIND=1)} +and @code{REAL(KIND=2)} take twice as much storage space as @code{REAL(KIND=1)}. +Further, it requires that @code{COMPLEX(KIND=1)} +entities be ordered such that when a @code{COMPLEX(KIND=1)} variable is +storage-associated (such as via @code{EQUIVALENCE}) +with a two-element @code{REAL(KIND=1)} array named @samp{R}, @samp{R(1)} +corresponds to the real element and @samp{R(2)} to the imaginary +element of the @code{COMPLEX(KIND=1)} variable. + +(Few requirements as to precision or ranges of any of these are +placed on the implementation, nor is the relationship of storage sizes of +these types to the @code{CHARACTER} type specified, by the standard.) + +@command{g77} follows the above requirements, warning when compiling +a program requires placement of items in memory that contradict the +requirements of the target architecture. +(For example, a program can require placement of a @code{REAL(KIND=2)} +on a boundary that is not an even multiple of its size, but still an +even multiple of the size of a @code{REAL(KIND=1)} variable. +On some target architectures, using the canonical +mapping of Fortran types to underlying architectural types, such +placement is prohibited by the machine definition or +the Application Binary Interface (ABI) in force for +the configuration defined for building @command{gcc} and @command{g77}. +@command{g77} warns about such +situations when it encounters them.) + +@command{g77} follows consistent rules for configuring the mapping between Fortran +types, including the @samp{*@var{n}} notation, and the underlying architectural +types as accessed by a similarly-configured applicable version of the +@command{gcc} compiler. +These rules offer a widely portable, consistent Fortran/C +environment, although they might well conflict with the expectations of +users of Fortran compilers designed and written for particular +architectures. + +These rules are based on the configuration that is in force for the +version of @command{gcc} built in the same release as @command{g77} (and +which was therefore used to build both the @command{g77} compiler +components and the @code{libg2c} run-time library): + +@table @code +@cindex REAL(KIND=1) type +@cindex types, REAL(KIND=1) +@item REAL(KIND=1) +Same as @code{float} type. + +@cindex REAL(KIND=2) type +@cindex types, REAL(KIND=2) +@item REAL(KIND=2) +Same as whatever floating-point type that is twice the size +of a @code{float}---usually, this is a @code{double}. + +@cindex INTEGER(KIND=1) type +@cindex types, INTEGER(KIND=1) +@item INTEGER(KIND=1) +Same as an integral type that is occupies the same amount +of memory storage as @code{float}---usually, this is either +an @code{int} or a @code{long int}. + +@cindex LOGICAL(KIND=1) type +@cindex types, LOGICAL(KIND=1) +@item LOGICAL(KIND=1) +Same @command{gcc} type as @code{INTEGER(KIND=1)}. + +@cindex INTEGER(KIND=2) type +@cindex types, INTEGER(KIND=2) +@item INTEGER(KIND=2) +Twice the size, and usually nearly twice the range, +as @code{INTEGER(KIND=1)}---usually, this is either +a @code{long int} or a @code{long long int}. + +@cindex LOGICAL(KIND=2) type +@cindex types, LOGICAL(KIND=2) +@item LOGICAL(KIND=2) +Same @command{gcc} type as @code{INTEGER(KIND=2)}. + +@cindex INTEGER(KIND=3) type +@cindex types, INTEGER(KIND=3) +@item INTEGER(KIND=3) +Same @command{gcc} type as signed @code{char}. + +@cindex LOGICAL(KIND=3) type +@cindex types, LOGICAL(KIND=3) +@item LOGICAL(KIND=3) +Same @command{gcc} type as @code{INTEGER(KIND=3)}. + +@cindex INTEGER(KIND=6) type +@cindex types, INTEGER(KIND=6) +@item INTEGER(KIND=6) +Twice the size, and usually nearly twice the range, +as @code{INTEGER(KIND=3)}---usually, this is +a @code{short}. + +@cindex LOGICAL(KIND=6) type +@cindex types, LOGICAL(KIND=6) +@item LOGICAL(KIND=6) +Same @command{gcc} type as @code{INTEGER(KIND=6)}. + +@cindex COMPLEX(KIND=1) type +@cindex types, COMPLEX(KIND=1) +@item COMPLEX(KIND=1) +Two @code{REAL(KIND=1)} scalars (one for the real part followed by +one for the imaginary part). + +@cindex COMPLEX(KIND=2) type +@cindex types, COMPLEX(KIND=2) +@item COMPLEX(KIND=2) +Two @code{REAL(KIND=2)} scalars. + +@cindex *@var{n} notation +@item @var{numeric-type}*@var{n} +(Where @var{numeric-type} is any type other than @code{CHARACTER}.) +Same as whatever @command{gcc} type occupies @var{n} times the storage +space of a @command{gcc} @code{char} item. + +@cindex DOUBLE PRECISION type +@cindex types, DOUBLE PRECISION +@item DOUBLE PRECISION +Same as @code{REAL(KIND=2)}. + +@cindex DOUBLE COMPLEX type +@cindex types, DOUBLE COMPLEX +@item DOUBLE COMPLEX +Same as @code{COMPLEX(KIND=2)}. +@end table + +Note that the above are proposed correspondences and might change +in future versions of @command{g77}---avoid writing code depending +on them. + +Other types supported by @command{g77} +are derived from gcc types such as @code{char}, @code{short}, +@code{int}, @code{long int}, @code{long long int}, @code{long double}, +and so on. +That is, whatever types @command{gcc} already supports, @command{g77} supports +now or probably will support in a future version. +The rules for the @samp{@var{numeric-type}*@var{n}} notation +apply to these types, +and new values for @samp{@var{numeric-type}(KIND=@var{n})} will be +assigned in a way that encourages clarity, consistency, and portability. + +@node Compiler Constants +@section Compiler Constants +@cindex constants +@cindex types, constants + +@command{g77} strictly assigns types to @emph{all} constants not +documented as ``typeless'' (typeless constants including @samp{'1'Z}, +for example). +Many other Fortran compilers attempt to assign types to typed constants +based on their context. +This results in hard-to-find bugs, nonportable +code, and is not in the spirit (though it strictly follows the letter) +of the 77 and 90 standards. + +@command{g77} might offer, in a future release, explicit constructs by +which a wider variety of typeless constants may be specified, and/or +user-requested warnings indicating places where @command{g77} might differ +from how other compilers assign types to constants. + +@xref{Context-Sensitive Constants}, for more information on this issue. + +@node Compiler Intrinsics +@section Compiler Intrinsics + +@command{g77} offers an ever-widening set of intrinsics. +Currently these all are procedures (functions and subroutines). + +Some of these intrinsics are unimplemented, but their names reserved +to reduce future problems with existing code as they are implemented. +Others are implemented as part of the GNU Fortran language, while +yet others are provided for compatibility with other dialects of +Fortran but are not part of the GNU Fortran language. + +To manage these distinctions, @command{g77} provides intrinsic @emph{groups}, +a facility that is simply an extension of the intrinsic groups provided +by the GNU Fortran language. + +@menu +* Intrinsic Groups:: How intrinsics are grouped for easy management. +* Other Intrinsics:: Intrinsics other than those in the GNU + Fortran language. +@end menu + +@node Intrinsic Groups +@subsection Intrinsic Groups +@cindex groups of intrinsics +@cindex intrinsics, groups + +A given specific intrinsic belongs in one or more groups. +Each group is deleted, disabled, hidden, or enabled +by default or a command-line option. +The meaning of each term follows. + +@table @b +@cindex deleted intrinsics +@cindex intrinsics, deleted +@item Deleted +No intrinsics are recognized as belonging to that group. + +@cindex disabled intrinsics +@cindex intrinsics, disabled +@item Disabled +Intrinsics are recognized as belonging to the group, but +references to them (other than via the @code{INTRINSIC} statement) +are disallowed through that group. + +@cindex hidden intrinsics +@cindex intrinsics, hidden +@item Hidden +Intrinsics in that group are recognized and enabled (if implemented) +@emph{only} if the first mention of the actual name of an intrinsic +in a program unit is in an @code{INTRINSIC} statement. + +@cindex enabled intrinsics +@cindex intrinsics, enabled +@item Enabled +Intrinsics in that group are recognized and enabled (if implemented). +@end table + +The distinction between deleting and disabling a group is illustrated +by the following example. +Assume intrinsic @samp{FOO} belongs only to group @samp{FGR}. +If group @samp{FGR} is deleted, the following program unit will +successfully compile, because @samp{FOO()} will be seen as a +reference to an external function named @samp{FOO}: + +@example +PRINT *, FOO() +END +@end example + +@noindent +If group @samp{FGR} is disabled, compiling the above program will produce +diagnostics, either because the @samp{FOO} intrinsic is improperly invoked +or, if properly invoked, it is not enabled. +To change the above program so it references an external function @samp{FOO} +instead of the disabled @samp{FOO} intrinsic, +add the following line to the top: + +@example +EXTERNAL FOO +@end example + +@noindent +So, deleting a group tells @command{g77} to pretend as though the intrinsics in +that group do not exist at all, whereas disabling it tells @command{g77} to +recognize them as (disabled) intrinsics in intrinsic-like contexts. + +Hiding a group is like enabling it, but the intrinsic must be first +named in an @code{INTRINSIC} statement to be considered a reference to the +intrinsic rather than to an external procedure. +This might be the ``safest'' way to treat a new group of intrinsics +when compiling old +code, because it allows the old code to be generally written as if +those new intrinsics never existed, but to be changed to use them +by inserting @code{INTRINSIC} statements in the appropriate places. +However, it should be the goal of development to use @code{EXTERNAL} +for all names of external procedures that might be intrinsic names. + +If an intrinsic is in more than one group, it is enabled if any of its +containing groups are enabled; if not so enabled, it is hidden if +any of its containing groups are hidden; if not so hidden, it is disabled +if any of its containing groups are disabled; if not so disabled, it is +deleted. +This extra complication is necessary because some intrinsics, +such as @code{IBITS}, belong to more than one group, and hence should be +enabled if any of the groups to which they belong are enabled, and so +on. + +The groups are: + +@cindex intrinsics, groups of +@cindex groups of intrinsics +@table @code +@cindex @code{badu77} intrinsics group +@item badu77 +UNIX intrinsics having inappropriate forms (usually functions that +have intended side effects). + +@cindex @code{gnu} intrinsics group +@item gnu +Intrinsics the GNU Fortran language supports that are extensions to +the Fortran standards (77 and 90). + +@cindex @command{f2c} intrinsics group +@item f2c +Intrinsics supported by AT&T's @command{f2c} converter and/or @code{libf2c}. + +@cindex @code{f90} intrinsics group +@item f90 +Fortran 90 intrinsics. + +@cindex @code{mil} intrinsics group +@item mil +MIL-STD 1753 intrinsics (@code{MVBITS}, @code{IAND}, @code{BTEST}, and so on). + +@cindex @code{mil} intrinsics group +@item unix +UNIX intrinsics (@code{IARGC}, @code{EXIT}, @code{ERF}, and so on). + +@cindex @code{mil} intrinsics group +@item vxt +VAX/VMS FORTRAN (current as of v4) intrinsics. +@end table + +@node Other Intrinsics +@subsection Other Intrinsics +@cindex intrinsics, others +@cindex other intrinsics + +@command{g77} supports intrinsics other than those in the GNU Fortran +language proper. +This set of intrinsics is described below. + +@ifinfo +(Note that the empty lines appearing in the menu below +are not intentional---they result from a bug in the +@code{makeinfo} program.) +@end ifinfo + +@c The actual documentation for intrinsics comes from +@c intdoc.texi, which in turn is automatically generated +@c from the internal g77 tables in intrin.def _and_ the +@c largely hand-written text in intdoc.h. So, if you want +@c to change or add to existing documentation on intrinsics, +@c you probably want to edit intdoc.h. +@c +@clear familyF77 +@clear familyGNU +@clear familyASC +@clear familyMIL +@clear familyF90 +@set familyVXT +@set familyFVZ +@clear familyF2C +@clear familyF2U +@set familyBADU77 +@include intdoc.texi + +@node Other Compilers +@chapter Other Compilers + +An individual Fortran source file can be compiled to +an object (@file{*.o}) file instead of to the final +program executable. +This allows several portions of a program to be compiled +at different times and linked together whenever a new +version of the program is needed. +However, it introduces the issue of @dfn{object compatibility} +across the various object files (and libraries, or @file{*.a} +files) that are linked together to produce any particular +executable file. + +Object compatibility is an issue when combining, in one +program, Fortran code compiled by more than one compiler +(or more than one configuration of a compiler). +If the compilers +disagree on how to transform the names of procedures, there +will normally be errors when linking such programs. +Worse, if the compilers agree on naming, but disagree on issues +like how to pass parameters, return arguments, and lay out +@code{COMMON} areas, the earliest detected errors might be the +incorrect results produced by the program (and that assumes +these errors are detected, which is not always the case). + +Normally, @command{g77} generates code that is +object-compatible with code generated by a version of +@command{f2c} configured (with, for example, @file{f2c.h} definitions) +to be generally compatible with @command{g77} as built by @command{gcc}. +(Normally, @command{f2c} will, by default, conform to the appropriate +configuration, but it is possible that older or perhaps even newer +versions of @command{f2c}, or versions having certain configuration changes +to @command{f2c} internals, will produce object files that are +incompatible with @command{g77}.) + +For example, a Fortran string subroutine +argument will become two arguments on the C side: a @code{char *} +and an @code{int} length. + +Much of this compatibility results from the fact that +@command{g77} uses the same run-time library, +@code{libf2c}, used by @command{f2c}, +though @command{g77} gives its version the name @code{libg2c} +so as to avoid conflicts when linking, +installing them in the same directories, +and so on. + +Other compilers might or might not generate code that +is object-compatible with @code{libg2c} and current @command{g77}, +and some might offer such compatibility only when explicitly +selected via a command-line option to the compiler. + +@emph{Note: This portion of the documentation definitely needs a lot +of work!} + +@menu +* Dropping f2c Compatibility:: When speed is more important. +* Compilers Other Than f2c:: Interoperation with code from other compilers. +@end menu + +@node Dropping f2c Compatibility +@section Dropping @command{f2c} Compatibility + +Specifying @option{-fno-f2c} allows @command{g77} to generate, in +some cases, faster code, by not needing to allow to the possibility +of linking with code compiled by @command{f2c}. + +For example, this affects how @code{REAL(KIND=1)}, +@code{COMPLEX(KIND=1)}, and @code{COMPLEX(KIND=2)} functions are called. +With @option{-fno-f2c}, they are +compiled as returning the appropriate @command{gcc} type +(@code{float}, @code{__complex__ float}, @code{__complex__ double}, +in many configurations). + +With @option{-ff2c} in force, they +are compiled differently (with perhaps slower run-time performance) +to accommodate the restrictions inherent in @command{f2c}'s use of K&R +C as an intermediate language---@code{REAL(KIND=1)} functions +return C's @code{double} type, while @code{COMPLEX} functions return +@code{void} and use an extra argument pointing to a place for the functions to +return their values. + +It is possible that, in some cases, leaving @option{-ff2c} in force +might produce faster code than using @option{-fno-f2c}. +Feel free to experiment, but remember to experiment with changing the way +@emph{entire programs and their Fortran libraries are compiled} at +a time, since this sort of experimentation affects the interface +of code generated for a Fortran source file---that is, it affects +object compatibility. + +Note that @command{f2c} compatibility is a fairly static target to achieve, +though not necessarily perfectly so, since, like @command{g77}, it is +still being improved. +However, specifying @option{-fno-f2c} causes @command{g77} +to generate code that will probably be incompatible with code +generated by future versions of @command{g77} when the same option +is in force. +You should make sure you are always able to recompile complete +programs from source code when upgrading to new versions of @command{g77} +or @command{f2c}, especially when using options such as @option{-fno-f2c}. + +Therefore, if you are using @command{g77} to compile libraries and other +object files for possible future use and you don't want to require +recompilation for future use with subsequent versions of @command{g77}, +you might want to stick with @command{f2c} compatibility for now, and +carefully watch for any announcements about changes to the +@command{f2c}/@code{libf2c} interface that might affect existing programs +(thus requiring recompilation). + +It is probable that a future version of @command{g77} will not, +by default, generate object files compatible with @command{f2c}, +and that version probably would no longer use @code{libf2c}. +If you expect to depend on this compatibility in the +long term, use the options @samp{-ff2c -ff2c-library} when compiling +all of the applicable code. +This should cause future versions of @command{g77} either to produce +compatible code (at the expense of the availability of some features and +performance), or at the very least, to produce diagnostics. + +(The library @command{g77} produces will no longer be named @file{libg2c} +when it is no longer generally compatible with @file{libf2c}. +It will likely be referred to, and, if installed as a distinct +library, named @code{libg77}, or some other as-yet-unused name.) + +@node Compilers Other Than f2c +@section Compilers Other Than @command{f2c} + +On systems with Fortran compilers other than @command{f2c} and @command{g77}, +code compiled by @command{g77} is not expected to work +well with code compiled by the native compiler. +(This is true for @command{f2c}-compiled objects as well.) +Libraries compiled with the native compiler probably will have +to be recompiled with @command{g77} to be used with @command{g77}-compiled code. + +Reasons for such incompatibilities include: + +@itemize @bullet +@item +There might be differences in the way names of Fortran procedures +are translated for use in the system's object-file format. +For example, the statement @samp{CALL FOO} might be compiled +by @command{g77} to call a procedure the linker @command{ld} sees +given the name @samp{_foo_}, while the apparently corresponding +statement @samp{SUBROUTINE FOO} might be compiled by the +native compiler to define the linker-visible name @samp{_foo}, +or @samp{_FOO_}, and so on. + +@item +There might be subtle type mismatches which cause subroutine arguments +and function return values to get corrupted. + +This is why simply getting @command{g77} to +transform procedure names the same way a native +compiler does is not usually a good idea---unless +some effort has been made to ensure that, aside +from the way the two compilers transform procedure +names, everything else about the way they generate +code for procedure interfaces is identical. + +@item +Native compilers +use libraries of private I/O routines which will not be available +at link time unless you have the native compiler---and you would +have to explicitly ask for them. + +For example, on the Sun you +would have to add @samp{-L/usr/lang/SCx.x -lF77 -lV77} to the link +command. +@end itemize + +@node Other Languages +@chapter Other Languages + +@emph{Note: This portion of the documentation definitely needs a lot +of work!} + +@menu +* Interoperating with C and C++:: +@end menu + +@node Interoperating with C and C++ +@section Tools and advice for interoperating with C and C++ + +@cindex C, linking with +@cindex C++, linking with +@cindex linking with C +The following discussion assumes that you are running @command{g77} in @command{f2c} +compatibility mode, i.e.@: not using @option{-fno-f2c}. +It provides some +advice about quick and simple techniques for linking Fortran and C (or +C++), the most common requirement. +For the full story consult the +description of code generation. +@xref{Debugging and Interfacing}. + +When linking Fortran and C, it's usually best to use @command{g77} to do +the linking so that the correct libraries are included (including the +maths one). +If you're linking with C++ you will want to add +@option{-lstdc++}, @option{-lg++} or whatever. +If you need to use another +driver program (or @command{ld} directly), +you can find out what linkage +options @command{g77} passes by running @samp{g77 -v}. + +@menu +* C Interfacing Tools:: +* C Access to Type Information:: +* f2c Skeletons and Prototypes:: +* C++ Considerations:: +* Startup Code:: +@end menu + +@node C Interfacing Tools +@subsection C Interfacing Tools +@pindex f2c +@cindex cfortran.h +@cindex Netlib +Even if you don't actually use it as a compiler, @command{f2c} from +@uref{ftp://ftp.netlib.org/f2c/src}, can be a useful tool when you're +interfacing (linking) Fortran and C@. +@xref{f2c Skeletons and Prototypes,,Generating Skeletons and Prototypes with @command{f2c}}. + +To use @command{f2c} for this purpose you only need retrieve and +build the @file{src} directory from the distribution, consult the +@file{README} instructions there for machine-specifics, and install the +@command{f2c} program on your path. + +Something else that might be useful is @samp{cfortran.h} from +@uref{ftp://zebra.desy.de/cfortran}. +This is a fairly general tool which +can be used to generate interfaces for calling in both directions +between Fortran and C@. +It can be used in @command{f2c} mode with +@command{g77}---consult its documentation for details. + +@node C Access to Type Information +@subsection Accessing Type Information in C + +@cindex types, Fortran/C +Generally, C code written to link with +@command{g77} code---calling and/or being +called from Fortran---should @samp{#include <g2c.h>} to define the C +versions of the Fortran types. +Don't assume Fortran @code{INTEGER} types +correspond to C @code{int}s, for instance; instead, declare them as +@code{integer}, a type defined by @file{g2c.h}. +@file{g2c.h} is installed where @command{gcc} will find it by +default, assuming you use a copy of @command{gcc} compatible with +@command{g77}, probably built at the same time as @command{g77}. + +@node f2c Skeletons and Prototypes +@subsection Generating Skeletons and Prototypes with @command{f2c} + +@pindex f2c +@cindex -fno-second-underscore +A simple and foolproof way to write @command{g77}-callable C routines---e.g.@: to +interface with an existing library---is to write a file (named, for +example, @file{fred.f}) of dummy Fortran +skeletons comprising just the declaration of the routine(s) and dummy +arguments plus @code{END} statements. +Then run @command{f2c} on file @file{fred.f} to produce @file{fred.c} +into which you can edit +useful code, confident the calling sequence is correct, at least. +(There are some errors otherwise commonly made in generating C +interfaces with @command{f2c} conventions, +such as not using @code{doublereal} +as the return type of a @code{REAL} @code{FUNCTION}.) + +@pindex ftnchek +@command{f2c} also can help with calling Fortran from C, using its +@option{-P} option to generate C prototypes appropriate for calling the +Fortran.@footnote{The files generated like this can also be used for +inter-unit consistency checking of dummy and actual arguments, although +the @command{ftnchek} tool from @uref{ftp://ftp.netlib.org/fortran} +or @uref{ftp://ftp.dsm.fordham.edu} is +probably better for this purpose.} +If the Fortran code containing any +routines to be called from C is in file @file{joe.f}, use the command +@kbd{f2c -P joe.f} to generate the file @file{joe.P} containing +prototype information. +@code{#include} this in the C which has to call +the Fortran routines to make sure you get it right. + +@xref{Arrays,,Arrays (DIMENSION)}, for information on the differences +between the way Fortran (including compilers like @command{g77}) and +C handle arrays. + +@node C++ Considerations +@subsection C++ Considerations + +@cindex C++ +@command{f2c} can be used to generate suitable code for compilation with a +C++ system using the @option{-C++} option. +The important thing about linking @command{g77}-compiled +code with C++ is that the prototypes for the @command{g77} +routines must specify C linkage to avoid name mangling. +So, use an @samp{extern "C"} declaration. +@command{f2c}'s @option{-C++} option will not take care +of this when generating skeletons or prototype files as above, however, +it will avoid clashes with C++ reserved words in addition to those in C@. + +@node Startup Code +@subsection Startup Code + +@cindex startup code +@cindex run-time, initialization +@cindex initialization, run-time +Unlike with some runtime systems, +it shouldn't be necessary +(unless there are bugs) +to use a Fortran main program unit to ensure the +runtime---specifically the I/O system---is initialized. + +However, to use the @command{g77} intrinsics @code{GETARG} and @code{IARGC}, +either the @code{main} routine from the @file{libg2c} library must be used, +or the @code{f_setarg} routine +(new as of @code{egcs} version 1.1 and @command{g77} version 0.5.23) +must be called with the appropriate @code{argc} and @code{argv} arguments +prior to the program calling @code{GETARG} or @code{IARGC}. + +To provide more flexibility for mixed-language programming +involving @command{g77} while allowing for shared libraries, +as of @code{egcs} version 1.1 and @command{g77} version 0.5.23, +@command{g77}'s @code{main} routine in @code{libg2c} +does the following, in order: + +@enumerate +@item +Calls @code{f_setarg} +with the incoming @code{argc} and @code{argv} arguments, +in the same order as for @code{main} itself. + +This sets up the command-line environment +for @code{GETARG} and @code{IARGC}. + +@item +Calls @code{f_setsig} (with no arguments). + +This sets up the signaling and exception environment. + +@item +Calls @code{f_init} (with no arguments). + +This initializes the I/O environment, +though that should not be necessary, +as all I/O functions in @code{libf2c} +are believed to call @code{f_init} automatically, +if necessary. + +(A future version of @command{g77} might skip this explicit step, +to speed up normal exit of a program.) + +@item +Arranges for @code{f_exit} to be called (with no arguments) +when the program exits. + +This ensures that the I/O environment is properly shut down +before the program exits normally. +Otherwise, output buffers might not be fully flushed, +scratch files might not be deleted, and so on. + +The simple way @code{main} does this is +to call @code{f_exit} itself after calling +@code{MAIN__} (in the next step). + +However, this does not catch the cases where the program +might call @code{exit} directly, +instead of using the @code{EXIT} intrinsic +(implemented as @code{exit_} in @code{libf2c}). + +So, @code{main} attempts to use +the operating environment's @code{onexit} or @code{atexit} +facility, if available, +to cause @code{f_exit} to be called automatically +upon any invocation of @code{exit}. + +@item +Calls @code{MAIN__} (with no arguments). + +This starts executing the Fortran main program unit for +the application. +(Both @command{g77} and @command{f2c} currently compile a main +program unit so that its global name is @code{MAIN__}.) + +@item +If no @code{onexit} or @code{atexit} is provided by the system, +calls @code{f_exit}. + +@item +Calls @code{exit} with a zero argument, +to signal a successful program termination. + +@item +Returns a zero value to the caller, +to signal a successful program termination, +in case @code{exit} doesn't exit on the system. +@end enumerate + +All of the above names are C @code{extern} names, +i.e.@: not mangled. + +When using the @code{main} procedure provided by @command{g77} +without a Fortran main program unit, +you need to provide @code{MAIN__} +as the entry point for your C code. +(Make sure you link the object file that defines that +entry point with the rest of your program.) + +To provide your own @code{main} procedure +in place of @command{g77}'s, +make sure you specify the object file defining that procedure +@emph{before} @option{-lg2c} on the @command{g77} command line. +Since the @option{-lg2c} option is implicitly provided, +this is usually straightforward. +(Use the @option{--verbose} option to see how and where +@command{g77} implicitly adds @option{-lg2c} in a command line +that will link the program. +Feel free to specify @option{-lg2c} explicitly, +as appropriate.) + +However, when providing your own @code{main}, +make sure you perform the appropriate tasks in the +appropriate order. +For example, if your @code{main} does not call @code{f_setarg}, +make sure the rest of your application does not call +@code{GETARG} or @code{IARGC}. + +And, if your @code{main} fails to ensure that @code{f_exit} +is called upon program exit, +some files might end up incompletely written, +some scratch files might be left lying around, +and some existing files being written might be left +with old data not properly truncated at the end. + +Note that, generally, the @command{g77} operating environment +does not depend on a procedure named @code{MAIN__} actually +being called prior to any other @command{g77}-compiled code. +That is, @code{MAIN__} does not, itself, +set up any important operating-environment characteristics +upon which other code might depend. +This might change in future versions of @command{g77}, +with appropriate notification in the release notes. + +For more information, consult the source code for the above routines. +These are in @file{@value{path-libf2c}/libF77/}, named @file{main.c}, +@file{setarg.c}, @file{setsig.c}, @file{getarg_.c}, and @file{iargc_.c}. + +Also, the file @file{@value{path-g77}/com.c} contains the code @command{g77} +uses to open-code (inline) references to @code{IARGC}. + +@node Debugging and Interfacing +@chapter Debugging and Interfacing +@cindex debugging +@cindex interfacing +@cindex calling C routines +@cindex C routines calling Fortran +@cindex f2c compatibility + +GNU Fortran currently generates code that is object-compatible with +the @command{f2c} converter. +Also, it avoids limitations in the current GBE, such as the +inability to generate a procedure with +multiple entry points, by generating code that is structured +differently (in terms of procedure names, scopes, arguments, and +so on) than might be expected. + +As a result, writing code in other languages that calls on, is +called by, or shares in-memory data with @command{g77}-compiled code generally +requires some understanding of the way @command{g77} compiles code for +various constructs. + +Similarly, using a debugger to debug @command{g77}-compiled +code, even if that debugger supports native Fortran debugging, generally +requires this sort of information. + +This section describes some of the basic information on how +@command{g77} compiles code for constructs involving interfaces to other +languages and to debuggers. + +@emph{Caution:} Much or all of this information pertains to only the current +release of @command{g77}, sometimes even to using certain compiler options +with @command{g77} (such as @option{-fno-f2c}). +Do not write code that depends on this +information without clearly marking said code as nonportable and +subject to review for every new release of @command{g77}. +This information +is provided primarily to make debugging of code generated by this +particular release of @command{g77} easier for the user, and partly to make +writing (generally nonportable) interface code easier. +Both of these +activities require tracking changes in new version of @command{g77} as they +are installed, because new versions can change the behaviors +described in this section. + +@menu +* Main Program Unit:: How @command{g77} compiles a main program unit. +* Procedures:: How @command{g77} constructs parameter lists + for procedures. +* Functions:: Functions returning floating-point or character data. +* Names:: Naming of user-defined variables, procedures, etc. +* Common Blocks:: Accessing common variables while debugging. +* Local Equivalence Areas:: Accessing @code{EQUIVALENCE} while debugging. +* Complex Variables:: How @command{g77} performs complex arithmetic. +* Arrays:: Dealing with (possibly multi-dimensional) arrays. +* Adjustable Arrays:: Special consideration for adjustable arrays. +* Alternate Entry Points:: How @command{g77} implements alternate @code{ENTRY}. +* Alternate Returns:: How @command{g77} handles alternate returns. +* Assigned Statement Labels:: How @command{g77} handles @code{ASSIGN}. +* Run-time Library Errors:: Meanings of some @code{IOSTAT=} values. +@end menu + +@node Main Program Unit +@section Main Program Unit (PROGRAM) +@cindex PROGRAM statement +@cindex statements, PROGRAM + +When @command{g77} compiles a main program unit, it gives it the public +procedure name @code{MAIN__}. +The @code{libg2c} library has the actual @code{main()} procedure +as is typical of C-based environments, and +it is this procedure that performs some initial start-up +activity and then calls @code{MAIN__}. + +Generally, @command{g77} and @code{libg2c} are designed so that you need not +include a main program unit written in Fortran in your program---it +can be written in C or some other language. +Especially for I/O handling, this is the case, although @command{g77} version 0.5.16 +includes a bug fix for @code{libg2c} that solved a problem with using the +@code{OPEN} statement as the first Fortran I/O activity in a program +without a Fortran main program unit. + +However, if you don't intend to use @command{g77} (or @command{f2c}) to compile +your main program unit---that is, if you intend to compile a @code{main()} +procedure using some other language---you should carefully +examine the code for @code{main()} in @code{libg2c}, found in the source +file @file{@value{path-libf2c}/libF77/main.c}, to see what kinds of things +might need to be done by your @code{main()} in order to provide the +Fortran environment your Fortran code is expecting. + +@cindex @code{IArgC} intrinsic +@cindex intrinsics, @code{IArgC} +@cindex @code{GetArg} intrinsic +@cindex intrinsics, @code{GetArg} +For example, @code{libg2c}'s @code{main()} sets up the information used by +the @code{IARGC} and @code{GETARG} intrinsics. +Bypassing @code{libg2c}'s @code{main()} +without providing a substitute for this activity would mean +that invoking @code{IARGC} and @code{GETARG} would produce undefined +results. + +@cindex debugging +@cindex main program unit, debugging +@cindex main() +@cindex MAIN__() +@cindex .gdbinit +When debugging, one implication of the fact that @code{main()}, which +is the place where the debugged program ``starts'' from the +debugger's point of view, is in @code{libg2c} is that you won't be +starting your Fortran program at a point you recognize as your +Fortran code. + +The standard way to get around this problem is to set a break +point (a one-time, or temporary, break point will do) at +the entrance to @code{MAIN__}, and then run the program. +A convenient way to do so is to add the @command{gdb} command + +@example +tbreak MAIN__ +@end example + +@noindent +to the file @file{.gdbinit} in the directory in which you're debugging +(using @command{gdb}). + +After doing this, the debugger will see the current execution +point of the program as at the beginning of the main program +unit of your program. + +Of course, if you really want to set a break point at some +other place in your program and just start the program +running, without first breaking at @code{MAIN__}, +that should work fine. + +@node Procedures +@section Procedures (SUBROUTINE and FUNCTION) +@cindex procedures +@cindex SUBROUTINE statement +@cindex statements, SUBROUTINE +@cindex FUNCTION statement +@cindex statements, FUNCTION +@cindex signature of procedures + +Currently, @command{g77} passes arguments via reference---specifically, +by passing a pointer to the location in memory of a variable, array, +array element, a temporary location that holds the result of evaluating an +expression, or a temporary or permanent location that holds the value +of a constant. + +Procedures that accept @code{CHARACTER} arguments are implemented by +@command{g77} so that each @code{CHARACTER} argument has two actual arguments. + +The first argument occupies the expected position in the +argument list and has the user-specified name. +This argument +is a pointer to an array of characters, passed by the caller. + +The second argument is appended to the end of the user-specified +calling sequence and is named @samp{__g77_length_@var{x}}, where @var{x} +is the user-specified name. +This argument is of the C type @code{ftnlen} +(see @file{@value{path-libf2c}/g2c.h.in} for information on that type) and +is the number of characters the caller has allocated in the +array pointed to by the first argument. + +A procedure will ignore the length argument if @samp{X} is not declared +@code{CHARACTER*(*)}, because for other declarations, it knows the +length. +Not all callers necessarily ``know'' this, however, which +is why they all pass the extra argument. + +The contents of the @code{CHARACTER} argument are specified by the +address passed in the first argument (named after it). +The procedure can read or write these contents as appropriate. + +When more than one @code{CHARACTER} argument is present in the argument +list, the length arguments are appended in the order +the original arguments appear. +So @samp{CALL FOO('HI','THERE')} is implemented in +C as @samp{foo("hi","there",2,5);}, ignoring the fact that @command{g77} +does not provide the trailing null bytes on the constant +strings (@command{f2c} does provide them, but they are unnecessary in +a Fortran environment, and you should not expect them to be +there). + +Note that the above information applies to @code{CHARACTER} variables and +arrays @strong{only}. +It does @strong{not} apply to external @code{CHARACTER} +functions or to intrinsic @code{CHARACTER} functions. +That is, no second length argument is passed to @samp{FOO} in this case: + +@example +CHARACTER X +EXTERNAL X +CALL FOO(X) +@end example + +@noindent +Nor does @samp{FOO} expect such an argument in this case: + +@example +SUBROUTINE FOO(X) +CHARACTER X +EXTERNAL X +@end example + +Because of this implementation detail, if a program has a bug +such that there is disagreement as to whether an argument is +a procedure, and the type of the argument is @code{CHARACTER}, subtle +symptoms might appear. + +@node Functions +@section Functions (FUNCTION and RETURN) +@cindex functions +@cindex FUNCTION statement +@cindex statements, FUNCTION +@cindex RETURN statement +@cindex statements, RETURN +@cindex return type of functions + +@command{g77} handles in a special way functions that return the following +types: + +@itemize @bullet +@item +@code{CHARACTER} +@item +@code{COMPLEX} +@item +@code{REAL(KIND=1)} +@end itemize + +For @code{CHARACTER}, @command{g77} implements a subroutine (a C function +returning @code{void}) +with two arguments prepended: @samp{__g77_result}, which the caller passes +as a pointer to a @code{char} array expected to hold the return value, +and @samp{__g77_length}, which the caller passes as an @code{ftnlen} value +specifying the length of the return value as declared in the calling +program. +For @code{CHARACTER*(*)}, the called function uses @samp{__g77_length} +to determine the size of the array that @samp{__g77_result} points to; +otherwise, it ignores that argument. + +For @code{COMPLEX}, when @option{-ff2c} is in +force, @command{g77} implements +a subroutine with one argument prepended: @samp{__g77_result}, which the +caller passes as a pointer to a variable of the type of the function. +The called function writes the return value into this variable instead +of returning it as a function value. +When @option{-fno-f2c} is in force, +@command{g77} implements a @code{COMPLEX} function as @command{gcc}'s +@samp{__complex__ float} or @samp{__complex__ double} function +(or an emulation thereof, when @option{-femulate-complex} is in effect), +returning the result of the function in the same way as @command{gcc} would. + +For @code{REAL(KIND=1)}, when @option{-ff2c} is in force, @command{g77} implements +a function that actually returns @code{REAL(KIND=2)} (typically +C's @code{double} type). +When @option{-fno-f2c} is in force, @code{REAL(KIND=1)} +functions return @code{float}. + +@node Names +@section Names +@cindex symbol names +@cindex transforming symbol names + +Fortran permits each implementation to decide how to represent +names as far as how they're seen in other contexts, such as debuggers +and when interfacing to other languages, and especially as far +as how casing is handled. + +External names---names of entities that are public, or ``accessible'', +to all modules in a program---normally have an underscore (@samp{_}) +appended by @command{g77}, +to generate code that is compatible with @command{f2c}. +External names include names of Fortran things like common blocks, +external procedures (subroutines and functions, but not including +statement functions, which are internal procedures), and entry point +names. + +However, use of the @option{-fno-underscoring} option +disables this kind of transformation of external names (though inhibiting +the transformation certainly improves the chances of colliding with +incompatible externals written in other languages---but that +might be intentional. + +@cindex -fno-underscoring option +@cindex options, -fno-underscoring +@cindex -fno-second-underscore option +@cindex options, -fno-underscoring +When @option{-funderscoring} is in force, any name (external or local) +that already has at least one underscore in it is +implemented by @command{g77} by appending two underscores. +(This second underscore can be disabled via the +@option{-fno-second-underscore} option.) +External names are changed this way for @command{f2c} compatibility. +Local names are changed this way to avoid collisions with external names +that are different in the source code---@command{f2c} does the same thing, but +there's no compatibility issue there except for user expectations while +debugging. + +For example: + +@example +Max_Cost = 0 +@end example + +@cindex debugging +@noindent +Here, a user would, in the debugger, refer to this variable using the +name @samp{max_cost__} (or @samp{MAX_COST__} or @samp{Max_Cost__}, +as described below). +(We hope to improve @command{g77} in this regard in the future---don't +write scripts depending on this behavior! +Also, consider experimenting with the @option{-fno-underscoring} +option to try out debugging without having to massage names by +hand like this.) + +@command{g77} provides a number of command-line options that allow the user +to control how case mapping is handled for source files. +The default is the traditional UNIX model for Fortran compilers---names +are mapped to lower case. +Other command-line options can be specified to map names to upper +case, or to leave them exactly as written in the source file. + +For example: + +@example +Foo = 9.436 +@end example + +@noindent +Here, it is normally the case that the variable assigned will be named +@samp{foo}. +This would be the name to enter when using a debugger to +access the variable. + +However, depending on the command-line options specified, the +name implemented by @command{g77} might instead be @samp{FOO} or even +@samp{Foo}, thus affecting how debugging is done. + +Also: + +@example +Call Foo +@end example + +@noindent +This would normally call a procedure that, if it were in a separate C program, +be defined starting with the line: + +@example +void foo_() +@end example + +@noindent +However, @command{g77} command-line options could be used to change the casing +of names, resulting in the name @samp{FOO_} or @samp{Foo_} being given to the +procedure instead of @samp{foo_}, and the @option{-fno-underscoring} option +could be used to inhibit the appending of the underscore to the name. + +@node Common Blocks +@section Common Blocks (COMMON) +@cindex common blocks +@cindex @code{COMMON} statement +@cindex statements, @code{COMMON} + +@command{g77} names and lays out @code{COMMON} areas +the same way @command{f2c} does, +for compatibility with @command{f2c}. + +@node Local Equivalence Areas +@section Local Equivalence Areas (EQUIVALENCE) +@cindex equivalence areas +@cindex local equivalence areas +@cindex EQUIVALENCE statement +@cindex statements, EQUIVALENCE + +@command{g77} treats storage-associated areas involving a @code{COMMON} +block as explained in the section on common blocks. + +A local @code{EQUIVALENCE} area is a collection of variables and arrays +connected to each other in any way via @code{EQUIVALENCE}, none of which are +listed in a @code{COMMON} statement. + +(@emph{Note:} @command{g77} version 0.5.18 and earlier chose the name +for @var{x} using a different method when more than one name was +in the list of names of entities placed at the beginning of the +array. +Though the documentation specified that the first name listed in +the @code{EQUIVALENCE} statements was chosen for @var{x}, @command{g77} +in fact chose the name using a method that was so complicated, +it seemed easier to change it to an alphabetical sort than to describe the +previous method in the documentation.) + +@node Complex Variables +@section Complex Variables (COMPLEX) +@cindex complex variables +@cindex imaginary part +@cindex COMPLEX statement +@cindex statements, COMPLEX + +As of 0.5.20, @command{g77} defaults to handling @code{COMPLEX} types +(and related intrinsics, constants, functions, and so on) +in a manner that +makes direct debugging involving these types in Fortran +language mode difficult. + +Essentially, @command{g77} implements these types using an +internal construct similar to C's @code{struct}, at least +as seen by the @command{gcc} back end. + +Currently, the back end, when outputting debugging info with +the compiled code for the assembler to digest, does not detect +these @code{struct} types as being substitutes for Fortran +complex. +As a result, the Fortran language modes of debuggers such as +@command{gdb} see these types as C @code{struct} types, which +they might or might not support. + +Until this is fixed, switch to C language mode to work with +entities of @code{COMPLEX} type and then switch back to Fortran language +mode afterward. +(In @command{gdb}, this is accomplished via @samp{set lang c} and +either @samp{set lang fortran} or @samp{set lang auto}.) + +@node Arrays +@section Arrays (DIMENSION) +@cindex DIMENSION statement +@cindex statements, DIMENSION +@cindex array ordering +@cindex ordering, array +@cindex column-major ordering +@cindex row-major ordering +@cindex arrays + +Fortran uses ``column-major ordering'' in its arrays. +This differs from other languages, such as C, which use ``row-major ordering''. +The difference is that, with Fortran, array elements adjacent to +each other in memory differ in the @emph{first} subscript instead of +the last; @samp{A(5,10,20)} immediately follows @samp{A(4,10,20)}, +whereas with row-major ordering it would follow @samp{A(5,10,19)}. + +This consideration +affects not only interfacing with and debugging Fortran code, +it can greatly affect how code is designed and written, especially +when code speed and size is a concern. + +Fortran also differs from C, a popular language for interfacing and +to support directly in debuggers, in the way arrays are treated. +In C, arrays are single-dimensional and have interesting relationships +to pointers, neither of which is true for Fortran. +As a result, dealing with Fortran arrays from within +an environment limited to C concepts can be challenging. + +For example, accessing the array element @samp{A(5,10,20)} is easy enough +in Fortran (use @samp{A(5,10,20)}), but in C some difficult machinations +are needed. +First, C would treat the A array as a single-dimension array. +Second, C does not understand low bounds for arrays as does Fortran. +Third, C assumes a low bound of zero (0), while Fortran defaults to a +low bound of one (1) and can supports an arbitrary low bound. +Therefore, calculations must be done +to determine what the C equivalent of @samp{A(5,10,20)} would be, and these +calculations require knowing the dimensions of @samp{A}. + +For @samp{DIMENSION A(2:11,21,0:29)}, the calculation of the offset of +@samp{A(5,10,20)} would be: + +@example + (5-2) ++ (10-1)*(11-2+1) ++ (20-0)*(11-2+1)*(21-1+1) += 4293 +@end example + +@noindent +So the C equivalent in this case would be @samp{a[4293]}. + +When using a debugger directly on Fortran code, the C equivalent +might not work, because some debuggers cannot understand the notion +of low bounds other than zero. However, unlike @command{f2c}, @command{g77} +does inform the GBE that a multi-dimensional array (like @samp{A} +in the above example) is really multi-dimensional, rather than a +single-dimensional array, so at least the dimensionality of the array +is preserved. + +Debuggers that understand Fortran should have no trouble with +nonzero low bounds, but for non-Fortran debuggers, especially +C debuggers, the above example might have a C equivalent of +@samp{a[4305]}. +This calculation is arrived at by eliminating the subtraction +of the lower bound in the first parenthesized expression on each +line---that is, for @samp{(5-2)} substitute @samp{(5)}, for @samp{(10-1)} +substitute @samp{(10)}, and for @samp{(20-0)} substitute @samp{(20)}. +Actually, the implication of +this can be that the expression @samp{*(&a[2][1][0] + 4293)} works fine, +but that @samp{a[20][10][5]} produces the equivalent of +@samp{*(&a[0][0][0] + 4305)} because of the missing lower bounds. + +Come to think of it, perhaps +the behavior is due to the debugger internally compensating for +the lower bounds by offsetting the base address of @samp{a}, leaving +@samp{&a} set lower, in this case, than @samp{&a[2][1][0]} (the address of +its first element as identified by subscripts equal to the +corresponding lower bounds). + +You know, maybe nobody really needs to use arrays. + +@node Adjustable Arrays +@section Adjustable Arrays (DIMENSION) +@cindex arrays, adjustable +@cindex adjustable arrays +@cindex arrays, automatic +@cindex automatic arrays +@cindex DIMENSION statement +@cindex statements, DIMENSION +@cindex dimensioning arrays +@cindex arrays, dimensioning + +Adjustable and automatic arrays in Fortran require the implementation +(in this +case, the @command{g77} compiler) to ``memorize'' the expressions that +dimension the arrays each time the procedure is invoked. +This is so that subsequent changes to variables used in those +expressions, made during execution of the procedure, do not +have any effect on the dimensions of those arrays. + +For example: + +@example +REAL ARRAY(5) +DATA ARRAY/5*2/ +CALL X(ARRAY, 5) +END +SUBROUTINE X(A, N) +DIMENSION A(N) +N = 20 +PRINT *, N, A +END +@end example + +@noindent +Here, the implementation should, when running the program, print something +like: + +@example +20 2. 2. 2. 2. 2. +@end example + +@noindent +Note that this shows that while the value of @samp{N} was successfully +changed, the size of the @samp{A} array remained at 5 elements. + +To support this, @command{g77} generates code that executes before any user +code (and before the internally generated computed @code{GOTO} to handle +alternate entry points, as described below) that evaluates each +(nonconstant) expression in the list of subscripts for an +array, and saves the result of each such evaluation to be used when +determining the size of the array (instead of re-evaluating the +expressions). + +So, in the above example, when @samp{X} is first invoked, code is +executed that copies the value of @samp{N} to a temporary. +And that same temporary serves as the actual high bound for the single +dimension of the @samp{A} array (the low bound being the constant 1). +Since the user program cannot (legitimately) change the value +of the temporary during execution of the procedure, the size +of the array remains constant during each invocation. + +For alternate entry points, the code @command{g77} generates takes into +account the possibility that a dummy adjustable array is not actually +passed to the actual entry point being invoked at that time. +In that case, the public procedure implementing the entry point +passes to the master private procedure implementing all the +code for the entry points a @code{NULL} pointer where a pointer to that +adjustable array would be expected. +The @command{g77}-generated code +doesn't attempt to evaluate any of the expressions in the subscripts +for an array if the pointer to that array is @code{NULL} at run time in +such cases. +(Don't depend on this particular implementation +by writing code that purposely passes @code{NULL} pointers where the +callee expects adjustable arrays, even if you know the callee +won't reference the arrays---nor should you pass @code{NULL} pointers +for any dummy arguments used in calculating the bounds of such +arrays or leave undefined any values used for that purpose in +COMMON---because the way @command{g77} implements these things might +change in the future!) + +@node Alternate Entry Points +@section Alternate Entry Points (ENTRY) +@cindex alternate entry points +@cindex entry points +@cindex ENTRY statement +@cindex statements, ENTRY + +The GBE does not understand the general concept of +alternate entry points as Fortran provides via the ENTRY statement. +@command{g77} gets around this by using an approach to compiling procedures +having at least one @code{ENTRY} statement that is almost identical to the +approach used by @command{f2c}. +(An alternate approach could be used that +would probably generate faster, but larger, code that would also +be a bit easier to debug.) + +Information on how @command{g77} implements @code{ENTRY} is provided for those +trying to debug such code. +The choice of implementation seems +unlikely to affect code (compiled in other languages) that interfaces +to such code. + +@command{g77} compiles exactly one public procedure for the primary entry +point of a procedure plus each @code{ENTRY} point it specifies, as usual. +That is, in terms of the public interface, there is no difference +between + +@example +SUBROUTINE X +END +SUBROUTINE Y +END +@end example + +@noindent +and: + +@example +SUBROUTINE X +ENTRY Y +END +@end example + +The difference between the above two cases lies in the code compiled +for the @samp{X} and @samp{Y} procedures themselves, plus the fact that, +for the second case, an extra internal procedure is compiled. + +For every Fortran procedure with at least one @code{ENTRY} +statement, @command{g77} compiles an extra procedure +named @samp{__g77_masterfun_@var{x}}, where @var{x} is +the name of the primary entry point (which, in the above case, +using the standard compiler options, would be @samp{x_} in C). + +This extra procedure is compiled as a private procedure---that is, +a procedure not accessible by name to separately compiled modules. +It contains all the code in the program unit, including the code +for the primary entry point plus for every entry point. +(The code for each public procedure is quite short, and explained later.) + +The extra procedure has some other interesting characteristics. + +The argument list for this procedure is invented by @command{g77}. +It contains +a single integer argument named @samp{__g77_which_entrypoint}, +passed by value (as in Fortran's @samp{%VAL()} intrinsic), specifying the +entry point index---0 for the primary entry point, 1 for the +first entry point (the first @code{ENTRY} statement encountered), 2 for +the second entry point, and so on. + +It also contains, for functions returning @code{CHARACTER} and +(when @option{-ff2c} is in effect) @code{COMPLEX} functions, +and for functions returning different types among the +@code{ENTRY} statements (e.g. @samp{REAL FUNCTION R()} +containing @samp{ENTRY I()}), an argument named @samp{__g77_result} that +is expected at run time to contain a pointer to where to store +the result of the entry point. +For @code{CHARACTER} functions, this +storage area is an array of the appropriate number of characters; +for @code{COMPLEX} functions, it is the appropriate area for the return +type; for multiple-return-type functions, it is a union of all the supported return +types (which cannot include @code{CHARACTER}, since combining @code{CHARACTER} +and non-@code{CHARACTER} return types via @code{ENTRY} in a single function +is not supported by @command{g77}). + +For @code{CHARACTER} functions, the @samp{__g77_result} argument is followed +by yet another argument named @samp{__g77_length} that, at run time, +specifies the caller's expected length of the returned value. +Note that only @code{CHARACTER*(*)} functions and entry points actually +make use of this argument, even though it is always passed by +all callers of public @code{CHARACTER} functions (since the caller does not +generally know whether such a function is @code{CHARACTER*(*)} or whether +there are any other callers that don't have that information). + +The rest of the argument list is the union of all the arguments +specified for all the entry points (in their usual forms, e.g. +@code{CHARACTER} arguments have extra length arguments, all appended at +the end of this list). +This is considered the ``master list'' of +arguments. + +The code for this procedure has, before the code for the first +executable statement, code much like that for the following Fortran +statement: + +@smallexample + GOTO (100000,100001,100002), __g77_which_entrypoint +100000 @dots{}code for primary entry point@dots{} +100001 @dots{}code immediately following first ENTRY statement@dots{} +100002 @dots{}code immediately following second ENTRY statement@dots{} +@end smallexample + +@noindent +(Note that invalid Fortran statement labels and variable names +are used in the above example to highlight the fact that it +represents code generated by the @command{g77} internals, not code to be +written by the user.) + +It is this code that, when the procedure is called, picks which +entry point to start executing. + +Getting back to the public procedures (@samp{x} and @samp{Y} in the original +example), those procedures are fairly simple. +Their interfaces +are just like they would be if they were self-contained procedures +(without @code{ENTRY}), of course, since that is what the callers +expect. +Their code consists of simply calling the private +procedure, described above, with the appropriate extra arguments +(the entry point index, and perhaps a pointer to a multiple-type- +return variable, local to the public procedure, that contains +all the supported returnable non-character types). +For arguments +that are not listed for a given entry point that are listed for +other entry points, and therefore that are in the ``master list'' +for the private procedure, null pointers (in C, the @code{NULL} macro) +are passed. +Also, for entry points that are part of a multiple-type- +returning function, code is compiled after the call of the private +procedure to extract from the multi-type union the appropriate result, +depending on the type of the entry point in question, returning +that result to the original caller. + +When debugging a procedure containing alternate entry points, you +can either set a break point on the public procedure itself (e.g. +a break point on @samp{X} or @samp{Y}) or on the private procedure that +contains most of the pertinent code (e.g. @samp{__g77_masterfun_@var{x}}). +If you do the former, you should use the debugger's command to +``step into'' the called procedure to get to the actual code; with +the latter approach, the break point leaves you right at the +actual code, skipping over the public entry point and its call +to the private procedure (unless you have set a break point there +as well, of course). + +Further, the list of dummy arguments that is visible when the +private procedure is active is going to be the expanded version +of the list for whichever particular entry point is active, +as explained above, and the way in which return values are +handled might well be different from how they would be handled +for an equivalent single-entry function. + +@node Alternate Returns +@section Alternate Returns (SUBROUTINE and RETURN) +@cindex subroutines +@cindex alternate returns +@cindex SUBROUTINE statement +@cindex statements, SUBROUTINE +@cindex RETURN statement +@cindex statements, RETURN + +Subroutines with alternate returns (e.g. @samp{SUBROUTINE X(*)} and +@samp{CALL X(*50)}) are implemented by @command{g77} as functions returning +the C @code{int} type. +The actual alternate-return arguments are omitted from the calling sequence. +Instead, the caller uses +the return value to do a rough equivalent of the Fortran +computed-@code{GOTO} statement, as in @samp{GOTO (50), X()} in the +example above (where @samp{X} is quietly declared as an @code{INTEGER(KIND=1)} +function), and the callee just returns whatever integer +is specified in the @code{RETURN} statement for the subroutine +For example, @samp{RETURN 1} is implemented as @samp{X = 1} followed +by @samp{RETURN} +in C, and @samp{RETURN} by itself is @samp{X = 0} and @samp{RETURN}). + +@node Assigned Statement Labels +@section Assigned Statement Labels (ASSIGN and GOTO) +@cindex assigned statement labels +@cindex statement labels, assigned +@cindex ASSIGN statement +@cindex statements, ASSIGN +@cindex GOTO statement +@cindex statements, GOTO + +For portability to machines where a pointer (such as to a label, +which is how @command{g77} implements @code{ASSIGN} and its relatives, +the assigned-@code{GOTO} and assigned-@code{FORMAT}-I/O statements) +is wider (bitwise) than an @code{INTEGER(KIND=1)}, @command{g77} +uses a different memory location to hold the @code{ASSIGN}ed value of a variable +than it does the numerical value in that variable, unless the +variable is wide enough (can hold enough bits). + +In particular, while @command{g77} implements + +@example +I = 10 +@end example + +@noindent +as, in C notation, @samp{i = 10;}, it implements + +@example +ASSIGN 10 TO I +@end example + +@noindent +as, in GNU's extended C notation (for the label syntax), +@samp{__g77_ASSIGN_I = &&L10;} (where @samp{L10} is just a massaging +of the Fortran label @samp{10} to make the syntax C-like; @command{g77} doesn't +actually generate the name @samp{L10} or any other name like that, +since debuggers cannot access labels anyway). + +While this currently means that an @code{ASSIGN} statement does not +overwrite the numeric contents of its target variable, @emph{do not} +write any code depending on this feature. +@command{g77} has already changed this implementation across +versions and might do so in the future. +This information is provided only to make debugging Fortran programs +compiled with the current version of @command{g77} somewhat easier. +If there's no debugger-visible variable named @samp{__g77_ASSIGN_I} +in a program unit that does @samp{ASSIGN 10 TO I}, that probably +means @command{g77} has decided it can store the pointer to the label directly +into @samp{I} itself. + +@xref{Ugly Assigned Labels}, for information on a command-line option +to force @command{g77} to use the same storage for both normal and +assigned-label uses of a variable. + +@node Run-time Library Errors +@section Run-time Library Errors +@cindex IOSTAT= +@cindex error values +@cindex error messages +@cindex messages, run-time +@cindex I/O, errors + +The @code{libg2c} library currently has the following table to relate +error code numbers, returned in @code{IOSTAT=} variables, to messages. +This information should, in future versions of this document, be +expanded upon to include detailed descriptions of each message. + +In line with good coding practices, any of the numbers in the +list below should @emph{not} be directly written into Fortran +code you write. +Instead, make a separate @code{INCLUDE} file that defines +@code{PARAMETER} names for them, and use those in your code, +so you can more easily change the actual numbers in the future. + +The information below is culled from the definition +of @code{F_err} in @file{f/runtime/libI77/err.c} in the +@command{g77} source tree. + +@smallexample +100: "error in format" +101: "illegal unit number" +102: "formatted io not allowed" +103: "unformatted io not allowed" +104: "direct io not allowed" +105: "sequential io not allowed" +106: "can't backspace file" +107: "null file name" +108: "can't stat file" +109: "unit not connected" +110: "off end of record" +111: "truncation failed in endfile" +112: "incomprehensible list input" +113: "out of free space" +114: "unit not connected" +115: "read unexpected character" +116: "bad logical input field" +117: "bad variable type" +118: "bad namelist name" +119: "variable not in namelist" +120: "no end record" +121: "variable count incorrect" +122: "subscript for scalar variable" +123: "invalid array section" +124: "substring out of bounds" +125: "subscript out of bounds" +126: "can't read file" +127: "can't write file" +128: "'new' file exists" +129: "can't append to file" +130: "non-positive record number" +131: "I/O started while already doing I/O" +@end smallexample + +@node Collected Fortran Wisdom +@chapter Collected Fortran Wisdom +@cindex wisdom +@cindex legacy code +@cindex code, legacy +@cindex writing code +@cindex code, writing + +Most users of @command{g77} can be divided into two camps: + +@itemize @bullet +@item +Those writing new Fortran code to be compiled by @command{g77}. + +@item +Those using @command{g77} to compile existing, ``legacy'' code. +@end itemize + +Users writing new code generally understand most of the necessary +aspects of Fortran to write ``mainstream'' code, but often need +help deciding how to handle problems, such as the construction +of libraries containing @code{BLOCK DATA}. + +Users dealing with ``legacy'' code sometimes don't have much +experience with Fortran, but believe that the code they're compiling +already works when compiled by other compilers (and might +not understand why, as is sometimes the case, it doesn't work +when compiled by @command{g77}). + +The following information is designed to help users do a better job +coping with existing, ``legacy'' Fortran code, and with writing +new code as well. + +@menu +* Advantages Over f2c:: If @command{f2c} is so great, why @command{g77}? +* Block Data and Libraries:: How @command{g77} solves a common problem. +* Loops:: Fortran @code{DO} loops surprise many people. +* Working Programs:: Getting programs to work should be done first. +* Overly Convenient Options:: Temptations to avoid, habits to not form. +* Faster Programs:: Everybody wants these, but at what cost? +@end menu + +@node Advantages Over f2c +@section Advantages Over f2c + +Without @command{f2c}, @command{g77} would have taken much longer to +do and probably not been as good for quite a while. +Sometimes people who notice how much @command{g77} depends on, and +documents encouragement to use, @command{f2c} ask why @command{g77} +was created if @command{f2c} already existed. + +This section gives some basic answers to these questions, though it +is not intended to be comprehensive. + +@menu +* Language Extensions:: Features used by Fortran code. +* Diagnostic Abilities:: Abilities to spot problems early. +* Compiler Options:: Features helpful to accommodate legacy code, etc. +* Compiler Speed:: Speed of the compilation process. +* Program Speed:: Speed of the generated, optimized code. +* Ease of Debugging:: Debugging ease-of-use at the source level. +* Character and Hollerith Constants:: A byte saved is a byte earned. +@end menu + +@node Language Extensions +@subsection Language Extensions + +@command{g77} offers several extensions to FORTRAN 77 language that @command{f2c} +doesn't: + +@itemize @bullet +@item +Automatic arrays + +@item +@code{CYCLE} and @code{EXIT} + +@item +Construct names + +@item +@code{SELECT CASE} + +@item +@code{KIND=} and @code{LEN=} notation + +@item +Semicolon as statement separator + +@item +Constant expressions in @code{FORMAT} statements +(such as @samp{FORMAT(I<J>)}, +where @samp{J} is a @code{PARAMETER} named constant) + +@item +@code{MvBits} intrinsic + +@item +@code{libU77} (Unix-compatibility) library, +with routines known to compiler as intrinsics +(so they work even when compiler options are used +to change the interfaces used by Fortran routines) +@end itemize + +@command{g77} also implements iterative @code{DO} loops +so that they work even in the presence of certain ``extreme'' inputs, +unlike @command{f2c}. +@xref{Loops}. + +However, @command{f2c} offers a few that @command{g77} doesn't, such as: + +@itemize @bullet +@item +Intrinsics in @code{PARAMETER} statements + +@item +Array bounds expressions (such as @samp{REAL M(N(2))}) + +@item +@code{AUTOMATIC} statement +@end itemize + +It is expected that @command{g77} will offer some or all of these missing +features at some time in the future. + +@node Diagnostic Abilities +@subsection Diagnostic Abilities + +@command{g77} offers better diagnosis of problems in @code{FORMAT} statements. +@command{f2c} doesn't, for example, emit any diagnostic for +@samp{FORMAT(XZFAJG10324)}, +leaving that to be diagnosed, at run time, by +the @code{libf2c} run-time library. + +@node Compiler Options +@subsection Compiler Options + +@command{g77} offers compiler options that @command{f2c} doesn't, +most of which are designed to more easily accommodate +legacy code: + +@itemize @bullet +@item +Two that control the automatic appending of extra +underscores to external names + +@item +One that allows dollar signs (@samp{$}) in symbol names + +@item +A variety that control acceptance of various +``ugly'' constructs + +@item +Several that specify acceptable use of upper and lower case +in the source code + +@item +Many that enable, disable, delete, or hide +groups of intrinsics + +@item +One to specify the length of fixed-form source lines +(normally 72) + +@item +One to specify the the source code is written in +Fortran-90-style free-form +@end itemize + +However, @command{f2c} offers a few that @command{g77} doesn't, +like an option to have @code{REAL} default to @code{REAL*8}. +It is expected that @command{g77} will offer all of the +missing options pertinent to being a Fortran compiler +at some time in the future. + +@node Compiler Speed +@subsection Compiler Speed + +Saving the steps of writing and then rereading C code is a big reason +why @command{g77} should be able to compile code much faster than using +@command{f2c} in conjunction with the equivalent invocation of @command{gcc}. + +However, due to @command{g77}'s youth, lots of self-checking is still being +performed. +As a result, this improvement is as yet unrealized +(though the potential seems to be there for quite a big speedup +in the future). +It is possible that, as of version 0.5.18, @command{g77} +is noticeably faster compiling many Fortran source files than using +@command{f2c} in conjunction with @command{gcc}. + +@node Program Speed +@subsection Program Speed + +@command{g77} has the potential to better optimize code than @command{f2c}, +even when @command{gcc} is used to compile the output of @command{f2c}, +because @command{f2c} must necessarily +translate Fortran into a somewhat lower-level language (C) that cannot +preserve all the information that is potentially useful for optimization, +while @command{g77} can gather, preserve, and transmit that information directly +to the GBE. + +For example, @command{g77} implements @code{ASSIGN} and assigned +@code{GOTO} using direct assignment of pointers to labels and direct +jumps to labels, whereas @command{f2c} maps the assigned labels to +integer values and then uses a C @code{switch} statement to encode +the assigned @code{GOTO} statements. + +However, as is typical, theory and reality don't quite match, at least +not in all cases, so it is still the case that @command{f2c} plus @command{gcc} +can generate code that is faster than @command{g77}. + +Version 0.5.18 of @command{g77} offered default +settings and options, via patches to the @command{gcc} +back end, that allow for better program speed, though +some of these improvements also affected the performance +of programs translated by @command{f2c} and then compiled +by @command{g77}'s version of @command{gcc}. + +Version 0.5.20 of @command{g77} offers further performance +improvements, at least one of which (alias analysis) is +not generally applicable to @command{f2c} (though @command{f2c} +could presumably be changed to also take advantage of +this new capability of the @command{gcc} back end, assuming +this is made available in an upcoming release of @command{gcc}). + +@node Ease of Debugging +@subsection Ease of Debugging + +Because @command{g77} compiles directly to assembler code like @command{gcc}, +instead of translating to an intermediate language (C) as does @command{f2c}, +support for debugging can be better for @command{g77} than @command{f2c}. + +However, although @command{g77} might be somewhat more ``native'' in terms of +debugging support than @command{f2c} plus @command{gcc}, there still are a lot +of things ``not quite right''. +Many of the important ones should be resolved in the near future. + +For example, @command{g77} doesn't have to worry about reserved names +like @command{f2c} does. +Given @samp{FOR = WHILE}, @command{f2c} must necessarily +translate this to something @emph{other} than +@samp{for = while;}, because C reserves those words. + +However, @command{g77} does still uses things like an extra level of indirection +for @code{ENTRY}-laden procedures---in this case, because the back end doesn't +yet support multiple entry points. + +Another example is that, given + +@smallexample +COMMON A, B +EQUIVALENCE (B, C) +@end smallexample + +@noindent +the @command{g77} user should be able to access the variables directly, by name, +without having to traverse C-like structures and unions, while @command{f2c} +is unlikely to ever offer this ability (due to limitations in the +C language). + +Yet another example is arrays. +@command{g77} represents them to the debugger +using the same ``dimensionality'' as in the source code, while @command{f2c} +must necessarily convert them all to one-dimensional arrays to fit +into the confines of the C language. +However, the level of support +offered by debuggers for interactive Fortran-style access to arrays +as compiled by @command{g77} can vary widely. +In some cases, it can actually +be an advantage that @command{f2c} converts everything to widely supported +C semantics. + +In fairness, @command{g77} could do many of the things @command{f2c} does +to get things working at least as well as @command{f2c}---for now, +the developers prefer making @command{g77} work the +way they think it is supposed to, and finding help improving the +other products (the back end of @command{gcc}; @command{gdb}; and so on) +to get things working properly. + +@node Character and Hollerith Constants +@subsection Character and Hollerith Constants +@cindex character constants +@cindex constants, character +@cindex Hollerith constants +@cindex constants, Hollerith +@cindex trailing null byte +@cindex null byte, trailing +@cindex zero byte, trailing + +To avoid the extensive hassle that would be needed to avoid this, +@command{f2c} uses C character constants to encode character and Hollerith +constants. +That means a constant like @samp{'HELLO'} is translated to +@samp{"hello"} in C, which further means that an extra null byte is +present at the end of the constant. +This null byte is superfluous. + +@command{g77} does not generate such null bytes. +This represents significant +savings of resources, such as on systems where @file{/dev/null} or +@file{/dev/zero} represent bottlenecks in the systems' performance, +because @command{g77} simply asks for fewer zeros from the operating +system than @command{f2c}. +(Avoiding spurious use of zero bytes, each byte typically have +eight zero bits, also reduces the liabilities in case +Microsoft's rumored patent on the digits 0 and 1 is upheld.) + +@node Block Data and Libraries +@section Block Data and Libraries +@cindex block data and libraries +@cindex BLOCK DATA statement +@cindex statements, BLOCK DATA +@cindex libraries, containing BLOCK DATA +@cindex f2c compatibility +@cindex compatibility, f2c + +To ensure that block data program units are linked, especially a concern +when they are put into libraries, give each one a name (as in +@samp{BLOCK DATA FOO}) and make sure there is an @samp{EXTERNAL FOO} +statement in every program unit that uses any common block +initialized by the corresponding @code{BLOCK DATA}. +@command{g77} currently compiles a @code{BLOCK DATA} as if it were a +@code{SUBROUTINE}, +that is, it generates an actual procedure having the appropriate name. +The procedure does nothing but return immediately if it happens to be +called. +For @samp{EXTERNAL FOO}, where @samp{FOO} is not otherwise referenced in the +same program unit, @command{g77} assumes there exists a @samp{BLOCK DATA FOO} +in the program and ensures that by generating a +reference to it so the linker will make sure it is present. +(Specifically, @command{g77} outputs in the data section a static pointer to the +external name @samp{FOO}.) + +The implementation @command{g77} currently uses to make this work is +one of the few things not compatible with @command{f2c} as currently +shipped. +@command{f2c} currently does nothing with @samp{EXTERNAL FOO} except +issue a warning that @samp{FOO} is not otherwise referenced, +and, for @samp{BLOCK DATA FOO}, +@command{f2c} doesn't generate a dummy procedure with the name @samp{FOO}. +The upshot is that you shouldn't mix @command{f2c} and @command{g77} in +this particular case. +If you use @command{f2c} to compile @samp{BLOCK DATA FOO}, +then any @command{g77}-compiled program unit that says @samp{EXTERNAL FOO} +will result in an unresolved reference when linked. +If you do the +opposite, then @samp{FOO} might not be linked in under various +circumstances (such as when @samp{FOO} is in a library, or you're +using a ``clever'' linker---so clever, it produces a broken program +with little or no warning by omitting initializations of global data +because they are contained in unreferenced procedures). + +The changes you make to your code to make @command{g77} handle this situation, +however, appear to be a widely portable way to handle it. +That is, many systems permit it (as they should, since the +FORTRAN 77 standard permits @samp{EXTERNAL FOO} when @samp{FOO} +is a block data program unit), and of the ones +that might not link @samp{BLOCK DATA FOO} under some circumstances, most of +them appear to do so once @samp{EXTERNAL FOO} is present in the appropriate +program units. + +Here is the recommended approach to modifying a program containing +a program unit such as the following: + +@smallexample +BLOCK DATA FOO +COMMON /VARS/ X, Y, Z +DATA X, Y, Z / 3., 4., 5. / +END +@end smallexample + +@noindent +If the above program unit might be placed in a library module, then +ensure that every program unit in every program that references that +particular @code{COMMON} area uses the @code{EXTERNAL} statement +to force the area to be initialized. + +For example, change a program unit that starts with + +@smallexample +INTEGER FUNCTION CURX() +COMMON /VARS/ X, Y, Z +CURX = X +END +@end smallexample + +@noindent +so that it uses the @code{EXTERNAL} statement, as in: + +@smallexample +INTEGER FUNCTION CURX() +COMMON /VARS/ X, Y, Z +EXTERNAL FOO +CURX = X +END +@end smallexample + +@noindent +That way, @samp{CURX} is compiled by @command{g77} (and many other +compilers) so that the linker knows it must include @samp{FOO}, +the @code{BLOCK DATA} program unit that sets the initial values +for the variables in @samp{VAR}, in the executable program. + +@node Loops +@section Loops +@cindex DO statement +@cindex statements, DO +@cindex trips, number of +@cindex number of trips + +The meaning of a @code{DO} loop in Fortran is precisely specified +in the Fortran standard@dots{}and is quite different from what +many programmers might expect. + +In particular, Fortran iterative @code{DO} loops are implemented as if +the number of trips through the loop is calculated @emph{before} +the loop is entered. + +The number of trips for a loop is calculated from the @var{start}, +@var{end}, and @var{increment} values specified in a statement such as: + +@smallexample +DO @var{iter} = @var{start}, @var{end}, @var{increment} +@end smallexample + +@noindent +The trip count is evaluated using a fairly simple formula +based on the three values following the @samp{=} in the +statement, and it is that trip count that is effectively +decremented during each iteration of the loop. +If, at the beginning of an iteration of the loop, the +trip count is zero or negative, the loop terminates. +The per-loop-iteration modifications to @var{iter} are not +related to determining whether to terminate the loop. + +There are two important things to remember about the trip +count: + +@itemize @bullet +@item +It can be @emph{negative}, in which case it is +treated as if it was zero---meaning the loop is +not executed at all. + +@item +The type used to @emph{calculate} the trip count +is the same type as @var{iter}, but the final +calculation, and thus the type of the trip +count itself, always is @code{INTEGER(KIND=1)}. +@end itemize + +These two items mean that there are loops that cannot +be written in straightforward fashion using the Fortran @code{DO}. + +For example, on a system with the canonical 32-bit two's-complement +implementation of @code{INTEGER(KIND=1)}, the following loop will not work: + +@smallexample +DO I = -2000000000, 2000000000 +@end smallexample + +@noindent +Although the @var{start} and @var{end} values are well within +the range of @code{INTEGER(KIND=1)}, the @emph{trip count} is not. +The expected trip count is 40000000001, which is outside +the range of @code{INTEGER(KIND=1)} on many systems. + +Instead, the above loop should be constructed this way: + +@smallexample +I = -2000000000 +DO + IF (I .GT. 2000000000) EXIT + @dots{} + I = I + 1 +END DO +@end smallexample + +@noindent +The simple @code{DO} construct and the @code{EXIT} statement +(used to leave the innermost loop) +are F90 features that @command{g77} supports. + +Some Fortran compilers have buggy implementations of @code{DO}, +in that they don't follow the standard. +They implement @code{DO} as a straightforward translation +to what, in C, would be a @code{for} statement. +Instead of creating a temporary variable to hold the trip count +as calculated at run time, these compilers +use the iteration variable @var{iter} to control +whether the loop continues at each iteration. + +The bug in such an implementation shows up when the +trip count is within the range of the type of @var{iter}, +but the magnitude of @samp{ABS(@var{end}) + ABS(@var{incr})} +exceeds that range. For example: + +@smallexample +DO I = 2147483600, 2147483647 +@end smallexample + +@noindent +A loop started by the above statement will work as implemented +by @command{g77}, but the use, by some compilers, of a +more C-like implementation akin to + +@smallexample +for (i = 2147483600; i <= 2147483647; ++i) +@end smallexample + +@noindent +produces a loop that does not terminate, because @samp{i} +can never be greater than 2147483647, since incrementing it +beyond that value overflows @samp{i}, setting it to -2147483648. +This is a large, negative number that still is less than 2147483647. + +Another example of unexpected behavior of @code{DO} involves +using a nonintegral iteration variable @var{iter}, that is, +a @code{REAL} variable. +Consider the following program: + +@smallexample + DATA BEGIN, END, STEP /.1, .31, .007/ + DO 10 R = BEGIN, END, STEP + IF (R .GT. END) PRINT *, R, ' .GT. ', END, '!!' + PRINT *,R +10 CONTINUE + PRINT *,'LAST = ',R + IF (R .LE. END) PRINT *, R, ' .LE. ', END, '!!' + END +@end smallexample + +@noindent +A C-like view of @code{DO} would hold that the two ``exclamatory'' +@code{PRINT} statements are never executed. +However, this is the output of running the above program +as compiled by @command{g77} on a GNU/Linux ix86 system: + +@smallexample + .100000001 + .107000001 + .114 + .120999999 + @dots{} + .289000005 + .296000004 + .303000003 +LAST = .310000002 + .310000002 .LE. .310000002!! +@end smallexample + +Note that one of the two checks in the program turned up +an apparent violation of the programmer's expectation---yet, +the loop is correctly implemented by @command{g77}, in that +it has 30 iterations. +This trip count of 30 is correct when evaluated using +the floating-point representations for the @var{begin}, +@var{end}, and @var{incr} values (.1, .31, .007) on GNU/Linux +ix86 are used. +On other systems, an apparently more accurate trip count +of 31 might result, but, nevertheless, @command{g77} is +faithfully following the Fortran standard, and the result +is not what the author of the sample program above +apparently expected. +(Such other systems might, for different values in the @code{DATA} +statement, violate the other programmer's expectation, +for example.) + +Due to this combination of imprecise representation +of floating-point values and the often-misunderstood +interpretation of @code{DO} by standard-conforming +compilers such as @command{g77}, use of @code{DO} loops +with @code{REAL} iteration +variables is not recommended. +Such use can be caught by specifying @option{-Wsurprising}. +@xref{Warning Options}, for more information on this +option. + +@node Working Programs +@section Working Programs + +Getting Fortran programs to work in the first place can be +quite a challenge---even when the programs already work on +other systems, or when using other compilers. + +@command{g77} offers some facilities that might be useful for +tracking down bugs in such programs. + +@menu +* Not My Type:: +* Variables Assumed To Be Zero:: +* Variables Assumed To Be Saved:: +* Unwanted Variables:: +* Unused Arguments:: +* Surprising Interpretations of Code:: +* Aliasing Assumed To Work:: +* Output Assumed To Flush:: +* Large File Unit Numbers:: +* Floating-point precision:: +* Inconsistent Calling Sequences:: +@end menu + +@node Not My Type +@subsection Not My Type +@cindex mistyped variables +@cindex variables, mistyped +@cindex mistyped functions +@cindex functions, mistyped +@cindex implicit typing + +A fruitful source of bugs in Fortran source code is use, or +mis-use, of Fortran's implicit-typing feature, whereby the +type of a variable, array, or function is determined by the +first character of its name. + +Simple cases of this include statements like @samp{LOGX=9.227}, +without a statement such as @samp{REAL LOGX}. +In this case, @samp{LOGX} is implicitly given @code{INTEGER(KIND=1)} +type, with the result of the assignment being that it is given +the value @samp{9}. + +More involved cases include a function that is defined starting +with a statement like @samp{DOUBLE PRECISION FUNCTION IPS(@dots{})}. +Any caller of this function that does not also declare @samp{IPS} +as type @code{DOUBLE PRECISION} (or, in GNU Fortran, @code{REAL(KIND=2)}) +is likely to assume it returns +@code{INTEGER}, or some other type, leading to invalid results +or even program crashes. + +The @option{-Wimplicit} option might catch failures to +properly specify the types of +variables, arrays, and functions in the code. + +However, in code that makes heavy use of Fortran's +implicit-typing facility, this option might produce so +many warnings about cases that are working, it would be +hard to find the one or two that represent bugs. +This is why so many experienced Fortran programmers strongly +recommend widespread use of the @code{IMPLICIT NONE} statement, +despite it not being standard FORTRAN 77, to completely turn +off implicit typing. +(@command{g77} supports @code{IMPLICIT NONE}, as do almost all +FORTRAN 77 compilers.) + +Note that @option{-Wimplicit} catches only implicit typing of +@emph{names}. +It does not catch implicit typing of expressions such +as @samp{X**(2/3)}. +Such expressions can be buggy as well---in fact, @samp{X**(2/3)} +is equivalent to @samp{X**0}, due to the way Fortran expressions +are given types and then evaluated. +(In this particular case, the programmer probably wanted +@samp{X**(2./3.)}.) + +@node Variables Assumed To Be Zero +@subsection Variables Assumed To Be Zero +@cindex zero-initialized variables +@cindex variables, assumed to be zero +@cindex uninitialized variables + +Many Fortran programs were developed on systems that provided +automatic initialization of all, or some, variables and arrays +to zero. +As a result, many of these programs depend, sometimes +inadvertently, on this behavior, though to do so violates +the Fortran standards. + +You can ask @command{g77} for this behavior by specifying the +@option{-finit-local-zero} option when compiling Fortran code. +(You might want to specify @option{-fno-automatic} as well, +to avoid code-size inflation for non-optimized compilations.) + +Note that a program that works better when compiled with the +@option{-finit-local-zero} option +is almost certainly depending on a particular system's, +or compiler's, tendency to initialize some variables to zero. +It might be worthwhile finding such cases and fixing them, +using techniques such as compiling with the @option{-O -Wuninitialized} +options using @command{g77}. + +@node Variables Assumed To Be Saved +@subsection Variables Assumed To Be Saved +@cindex variables, retaining values across calls +@cindex saved variables +@cindex static variables + +Many Fortran programs were developed on systems that +saved the values of all, or some, variables and arrays +across procedure calls. +As a result, many of these programs depend, sometimes +inadvertently, on being able to assign a value to a +variable, perform a @code{RETURN} to a calling procedure, +and, upon subsequent invocation, reference the previously +assigned variable to obtain the value. + +They expect this despite not using the @code{SAVE} statement +to specify that the value in a variable is expected to survive +procedure returns and calls. +Depending on variables and arrays to retain values across +procedure calls without using @code{SAVE} to require it violates +the Fortran standards. + +You can ask @command{g77} to assume @code{SAVE} is specified for all +relevant (local) variables and arrays by using the +@option{-fno-automatic} option. + +Note that a program that works better when compiled with the +@option{-fno-automatic} option +is almost certainly depending on not having to use +the @code{SAVE} statement as required by the Fortran standard. +It might be worthwhile finding such cases and fixing them, +using techniques such as compiling with the @samp{-O -Wuninitialized} +options using @command{g77}. + +@node Unwanted Variables +@subsection Unwanted Variables + +The @option{-Wunused} option can find bugs involving +implicit typing, sometimes +more easily than using @option{-Wimplicit} in code that makes +heavy use of implicit typing. +An unused variable or array might indicate that the +spelling for its declaration is different from that of +its intended uses. + +Other than cases involving typos, unused variables rarely +indicate actual bugs in a program. +However, investigating such cases thoroughly has, on occasion, +led to the discovery of code that had not been completely +written---where the programmer wrote declarations as needed +for the whole algorithm, wrote some or even most of the code +for that algorithm, then got distracted and forgot that the +job was not complete. + +@node Unused Arguments +@subsection Unused Arguments +@cindex unused arguments +@cindex arguments, unused + +As with unused variables, It is possible that unused arguments +to a procedure might indicate a bug. +Compile with @samp{-W -Wunused} option to catch cases of +unused arguments. + +Note that @option{-W} also enables warnings regarding overflow +of floating-point constants under certain circumstances. + +@node Surprising Interpretations of Code +@subsection Surprising Interpretations of Code + +The @option{-Wsurprising} option can help find bugs involving +expression evaluation or in +the way @code{DO} loops with non-integral iteration variables +are handled. +Cases found by this option might indicate a difference of +interpretation between the author of the code involved, and +a standard-conforming compiler such as @command{g77}. +Such a difference might produce actual bugs. + +In any case, changing the code to explicitly do what the +programmer might have expected it to do, so @command{g77} and +other compilers are more likely to follow the programmer's +expectations, might be worthwhile, especially if such changes +make the program work better. + +@node Aliasing Assumed To Work +@subsection Aliasing Assumed To Work +@cindex -falias-check option +@cindex options, -falias-check +@cindex -fargument-alias option +@cindex options, -fargument-alias +@cindex -fargument-noalias option +@cindex options, -fargument-noalias +@cindex -fno-argument-noalias-global option +@cindex options, -fno-argument-noalias-global +@cindex aliasing +@cindex anti-aliasing +@cindex overlapping arguments +@cindex overlays +@cindex association, storage +@cindex storage association +@cindex scheduling of reads and writes +@cindex reads and writes, scheduling + +The @option{-falias-check}, @option{-fargument-alias}, +@option{-fargument-noalias}, +and @option{-fno-argument-noalias-global} options, +introduced in version 0.5.20 and +@command{g77}'s version 2.7.2.2.f.2 of @command{gcc}, +were withdrawn as of @command{g77} version 0.5.23 +due to their not being supported by @command{gcc} version 2.8. + +These options control the assumptions regarding aliasing +(overlapping) of writes and reads to main memory (core) made +by the @command{gcc} back end. + +The information below still is useful, but applies to +only those versions of @command{g77} that support the +alias analysis implied by support for these options. + +These options are effective only when compiling with @option{-O} +(specifying any level other than @option{-O0}) +or with @option{-falias-check}. + +The default for Fortran code is @option{-fargument-noalias-global}. +(The default for C code and code written in other C-based languages +is @option{-fargument-alias}. +These defaults apply regardless of whether you use @command{g77} or +@command{gcc} to compile your code.) + +Note that, on some systems, compiling with @option{-fforce-addr} in +effect can produce more optimal code when the default aliasing +options are in effect (and when optimization is enabled). + +If your program is not working when compiled with optimization, +it is possible it is violating the Fortran standards (77 and 90) +by relying on the ability to ``safely'' modify variables and +arrays that are aliased, via procedure calls, to other variables +and arrays, without using @code{EQUIVALENCE} to explicitly +set up this kind of aliasing. + +(The FORTRAN 77 standard's prohibition of this sort of +overlap, generally referred to therein as ``storage +association'', appears in Sections 15.9.3.6. +This prohibition allows implementations, such as @command{g77}, +to, for example, implement the passing of procedures and +even values in @code{COMMON} via copy operations into local, +perhaps more efficiently accessed temporaries at entry to a +procedure, and, where appropriate, via copy operations back +out to their original locations in memory at exit from that +procedure, without having to take into consideration the +order in which the local copies are updated by the code, +among other things.) + +To test this hypothesis, try compiling your program with +the @option{-fargument-alias} option, which causes the +compiler to revert to assumptions essentially the same as +made by versions of @command{g77} prior to 0.5.20. + +If the program works using this option, that strongly suggests +that the bug is in your program. +Finding and fixing the bug(s) should result in a program that +is more standard-conforming and that can be compiled by @command{g77} +in a way that results in a faster executable. + +(You might want to try compiling with @option{-fargument-noalias}, +a kind of half-way point, to see if the problem is limited to +aliasing between dummy arguments and @code{COMMON} variables---this +option assumes that such aliasing is not done, while still allowing +aliasing among dummy arguments.) + +An example of aliasing that is invalid according to the standards +is shown in the following program, which might @emph{not} produce +the expected results when executed: + +@smallexample +I = 1 +CALL FOO(I, I) +PRINT *, I +END + +SUBROUTINE FOO(J, K) +J = J + K +K = J * K +PRINT *, J, K +END +@end smallexample + +The above program attempts to use the temporary aliasing of the +@samp{J} and @samp{K} arguments in @samp{FOO} to effect a +pathological behavior---the simultaneous changing of the values +of @emph{both} @samp{J} and @samp{K} when either one of them +is written. + +The programmer likely expects the program to print these values: + +@example +2 4 +4 +@end example + +However, since the program is not standard-conforming, an +implementation's behavior when running it is undefined, because +subroutine @samp{FOO} modifies at least one of the arguments, +and they are aliased with each other. +(Even if one of the assignment statements was deleted, the +program would still violate these rules. +This kind of on-the-fly aliasing is permitted by the standard +only when none of the aliased items are defined, or written, +while the aliasing is in effect.) + +As a practical example, an optimizing compiler might schedule +the @samp{J =} part of the second line of @samp{FOO} @emph{after} +the reading of @samp{J} and @samp{K} for the @samp{J * K} expression, +resulting in the following output: + +@example +2 2 +2 +@end example + +Essentially, compilers are promised (by the standard and, therefore, +by programmers who write code they claim to be standard-conforming) +that if they cannot detect aliasing via static analysis of a single +program unit's @code{EQUIVALENCE} and @code{COMMON} statements, no +such aliasing exists. +In such cases, compilers are free to assume that an assignment to +one variable will not change the value of another variable, allowing +it to avoid generating code to re-read the value of the other +variable, to re-schedule reads and writes, and so on, to produce +a faster executable. + +The same promise holds true for arrays (as seen by the called +procedure)---an element of one dummy array cannot be aliased +with, or overlap, any element of another dummy array or be +in a @code{COMMON} area known to the procedure. + +(These restrictions apply only when the procedure defines, or +writes to, one of the aliased variables or arrays.) + +Unfortunately, there is no way to find @emph{all} possible cases of +violations of the prohibitions against aliasing in Fortran code. +Static analysis is certainly imperfect, as is run-time analysis, +since neither can catch all violations. +(Static analysis can catch all likely violations, and some that +might never actually happen, while run-time analysis can catch +only those violations that actually happen during a particular run. +Neither approach can cope with programs mixing Fortran code with +routines written in other languages, however.) + +Currently, @command{g77} provides neither static nor run-time facilities +to detect any cases of this problem, although other products might. +Run-time facilities are more likely to be offered by future +versions of @command{g77}, though patches improving @command{g77} so that +it provides either form of detection are welcome. + +@node Output Assumed To Flush +@subsection Output Assumed To Flush +@cindex ALWAYS_FLUSH +@cindex synchronous write errors +@cindex disk full +@cindex flushing output +@cindex fflush() +@cindex I/O, flushing +@cindex output, flushing +@cindex writes, flushing +@cindex NFS +@cindex network file system + +For several versions prior to 0.5.20, @command{g77} configured its +version of the @code{libf2c} run-time library so that one of +its configuration macros, @code{ALWAYS_FLUSH}, was defined. + +This was done as a result of a belief that many programs expected +output to be flushed to the operating system (under UNIX, via +the @code{fflush()} library call) with the result that errors, +such as disk full, would be immediately flagged via the +relevant @code{ERR=} and @code{IOSTAT=} mechanism. + +Because of the adverse effects this approach had on the performance +of many programs, @command{g77} no longer configures @code{libf2c} +(now named @code{libg2c} in its @command{g77} incarnation) +to always flush output. + +If your program depends on this behavior, either insert the +appropriate @samp{CALL FLUSH} statements, or modify the sources +to the @code{libg2c}, rebuild and reinstall @command{g77}, and +relink your programs with the modified library. + +(Ideally, @code{libg2c} would offer the choice at run-time, so +that a compile-time option to @command{g77} or @command{f2c} could +result in generating the appropriate calls to flushing or +non-flushing library routines.) + +Some Fortran programs require output +(writes) to be flushed to the operating system (under UNIX, +via the @code{fflush()} library call) so that errors, +such as disk full, are immediately flagged via the relevant +@code{ERR=} and @code{IOSTAT=} mechanism, instead of such +errors being flagged later as subsequent writes occur, forcing +the previously written data to disk, or when the file is +closed. + +Essentially, the difference can be viewed as synchronous error +reporting (immediate flagging of errors during writes) versus +asynchronous, or, more precisely, buffered error reporting +(detection of errors might be delayed). + +@code{libg2c} supports flagging write errors immediately when +it is built with the @code{ALWAYS_FLUSH} macro defined. +This results in a @code{libg2c} that runs slower, sometimes +quite a bit slower, under certain circumstances---for example, +accessing files via the networked file system NFS---but the +effect can be more reliable, robust file I/O. + +If you know that Fortran programs requiring this level of precision +of error reporting are to be compiled using the +version of @command{g77} you are building, you might wish to +modify the @command{g77} source tree so that the version of +@code{libg2c} is built with the @code{ALWAYS_FLUSH} macro +defined, enabling this behavior. + +To do this, find this line in @file{@value{path-libf2c}/f2c.h} in +your @command{g77} source tree: + +@example +/* #define ALWAYS_FLUSH */ +@end example + +Remove the leading @samp{/*@w{ }}, +so the line begins with @samp{#define}, +and the trailing @samp{@w{ }*/}. + +Then build or rebuild @command{g77} as appropriate. + +@node Large File Unit Numbers +@subsection Large File Unit Numbers +@cindex MXUNIT +@cindex unit numbers +@cindex maximum unit number +@cindex illegal unit number +@cindex increasing maximum unit number + +If your program crashes at run time with a message including +the text @samp{illegal unit number}, that probably is +a message from the run-time library, @code{libg2c}. + +The message means that your program has attempted to use a +file unit number that is out of the range accepted by +@code{libg2c}. +Normally, this range is 0 through 99, and the high end +of the range is controlled by a @code{libg2c} source-file +macro named @code{MXUNIT}. + +If you can easily change your program to use unit numbers +in the range 0 through 99, you should do so. + +As distributed, whether as part of @command{f2c} or @command{g77}, +@code{libf2c} accepts file unit numbers only in the range +0 through 99. +For example, a statement such as @samp{WRITE (UNIT=100)} causes +a run-time crash in @code{libf2c}, because the unit number, +100, is out of range. + +If you know that Fortran programs at your installation require +the use of unit numbers higher than 99, you can change the +value of the @code{MXUNIT} macro, which represents the maximum unit +number, to an appropriately higher value. + +To do this, edit the file @file{@value{path-libf2c}/libI77/fio.h} in your +@command{g77} source tree, changing the following line: + +@example +#define MXUNIT 100 +@end example + +Change the line so that the value of @code{MXUNIT} is defined to be +at least one @emph{greater} than the maximum unit number used by +the Fortran programs on your system. + +(For example, a program that does @samp{WRITE (UNIT=255)} would require +@code{MXUNIT} set to at least 256 to avoid crashing.) + +Then build or rebuild @command{g77} as appropriate. + +@emph{Note:} Changing this macro has @emph{no} effect on other limits +your system might place on the number of files open at the same time. +That is, the macro might allow a program to do @samp{WRITE (UNIT=100)}, +but the library and operating system underlying @code{libf2c} might +disallow it if many other files have already been opened (via @code{OPEN} or +implicitly via @code{READ}, @code{WRITE}, and so on). +Information on how to increase these other limits should be found +in your system's documentation. + +@node Floating-point precision +@subsection Floating-point precision + +@cindex IEEE 754 conformance +@cindex conformance, IEEE 754 +@cindex floating-point, precision +@cindex ix86 floating-point +@cindex x86 floating-point +If your program depends on exact IEEE 754 floating-point handling it may +help on some systems---specifically x86 or m68k hardware---to use +the @option{-ffloat-store} option or to reset the precision flag on the +floating-point unit. +@xref{Optimize Options}. + +However, it might be better simply to put the FPU into double precision +mode and not take the performance hit of @option{-ffloat-store}. On x86 +and m68k GNU systems you can do this with a technique similar to that +for turning on floating-point exceptions +(@pxref{Floating-point Exception Handling}). +The control word could be set to double precision by some code like this +one: +@smallexample +#include <fpu_control.h> +@{ + fpu_control_t cw = (_FPU_DEFAULT & ~_FPU_EXTENDED) | _FPU_DOUBLE; + _FPU_SETCW(cw); +@} +@end smallexample +(It is not clear whether this has any effect on the operation of the GNU +maths library, but we have no evidence of it causing trouble.) + +Some targets (such as the Alpha) may need special options for full IEEE +conformance. +@xref{Submodel Options,,Hardware Models and Configurations,gcc,Using +the GNU Compiler Collection (GCC)}. + +@node Inconsistent Calling Sequences +@subsection Inconsistent Calling Sequences + +@pindex ftnchek +@cindex floating-point, errors +@cindex ix86 FPU stack +@cindex x86 FPU stack +Code containing inconsistent calling sequences in the same file is +normally rejected---see @ref{GLOBALS}. +(Use, say, @command{ftnchek} to ensure +consistency across source files. +@xref{f2c Skeletons and Prototypes,, +Generating Skeletons and Prototypes with @command{f2c}}.) + +Mysterious errors, which may appear to be code generation problems, can +appear specifically on the x86 architecture with some such +inconsistencies. On x86 hardware, floating-point return values of +functions are placed on the floating-point unit's register stack, not +the normal stack. Thus calling a @code{REAL} or @code{DOUBLE PRECISION} +@code{FUNCTION} as some other sort of procedure, or vice versa, +scrambles the floating-point stack. This may break unrelated code +executed later. Similarly if, say, external C routines are written +incorrectly. + +@node Overly Convenient Options +@section Overly Convenient Command-line Options +@cindex overly convenient options +@cindex options, overly convenient + +These options should be used only as a quick-and-dirty way to determine +how well your program will run under different compilation models +without having to change the source. +Some are more problematic +than others, depending on how portable and maintainable you want the +program to be (and, of course, whether you are allowed to change it +at all is crucial). + +You should not continue to use these command-line options to compile +a given program, but rather should make changes to the source code: + +@table @code +@cindex -finit-local-zero option +@cindex options, -finit-local-zero +@item -finit-local-zero +(This option specifies that any uninitialized local variables +and arrays have default initialization to binary zeros.) + +Many other compilers do this automatically, which means lots of +Fortran code developed with those compilers depends on it. + +It is safer (and probably +would produce a faster program) to find the variables and arrays that +need such initialization and provide it explicitly via @code{DATA}, so that +@option{-finit-local-zero} is not needed. + +Consider using @option{-Wuninitialized} (which requires @option{-O}) to +find likely candidates, but +do not specify @option{-finit-local-zero} or @option{-fno-automatic}, +or this technique won't work. + +@cindex -fno-automatic option +@cindex options, -fno-automatic +@item -fno-automatic +(This option specifies that all local variables and arrays +are to be treated as if they were named in @code{SAVE} statements.) + +Many other compilers do this automatically, which means lots of +Fortran code developed with those compilers depends on it. + +The effect of this is that all non-automatic variables and arrays +are made static, that is, not placed on the stack or in heap storage. +This might cause a buggy program to appear to work better. +If so, rather than relying on this command-line option (and hoping all +compilers provide the equivalent one), add @code{SAVE} +statements to some or all program unit sources, as appropriate. +Consider using @option{-Wuninitialized} (which requires @option{-O}) +to find likely candidates, but +do not specify @option{-finit-local-zero} or @option{-fno-automatic}, +or this technique won't work. + +The default is @option{-fautomatic}, which tells @command{g77} to try +and put variables and arrays on the stack (or in fast registers) +where possible and reasonable. +This tends to make programs faster. + +@cindex automatic arrays +@cindex arrays, automatic +@emph{Note:} Automatic variables and arrays are not affected +by this option. +These are variables and arrays that are @emph{necessarily} automatic, +either due to explicit statements, or due to the way they are +declared. +Examples include local variables and arrays not given the +@code{SAVE} attribute in procedures declared @code{RECURSIVE}, +and local arrays declared with non-constant bounds (automatic +arrays). +Currently, @command{g77} supports only automatic arrays, not +@code{RECURSIVE} procedures or other means of explicitly +specifying that variables or arrays are automatic. + +@cindex -f@var{group}-intrinsics-hide option +@cindex options, -f@var{group}-intrinsics-hide +@item -f@var{group}-intrinsics-hide +Change the source code to use @code{EXTERNAL} for any external procedure +that might be the name of an intrinsic. +It is easy to find these using @option{-f@var{group}-intrinsics-disable}. +@end table + +@node Faster Programs +@section Faster Programs +@cindex speed, of programs +@cindex programs, speeding up + +Aside from the usual @command{gcc} options, such as @option{-O}, +@option{-ffast-math}, and so on, consider trying some of the +following approaches to speed up your program (once you get +it working). + +@menu +* Aligned Data:: +* Prefer Automatic Uninitialized Variables:: +* Avoid f2c Compatibility:: +* Use Submodel Options:: +@end menu + +@node Aligned Data +@subsection Aligned Data +@cindex alignment +@cindex data, aligned +@cindex stack, aligned +@cindex aligned data +@cindex aligned stack +@cindex Pentium optimizations +@cindex optimization, for Pentium + +On some systems, such as those with Pentium Pro CPUs, programs +that make heavy use of @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}) +might run much slower +than possible due to the compiler not aligning these 64-bit +values to 64-bit boundaries in memory. +(The effect also is present, though +to a lesser extent, on the 586 (Pentium) architecture.) + +The Intel x86 architecture generally ensures that these programs will +work on all its implementations, +but particular implementations (such as Pentium Pro) +perform better with more strict alignment. +(Such behavior isn't unique to the Intel x86 architecture.) +Other architectures might @emph{demand} 64-bit alignment +of 64-bit data. + +There are a variety of approaches to use to address this problem: + +@itemize @bullet +@item +@cindex @code{COMMON} layout +@cindex layout of @code{COMMON} blocks +Order your @code{COMMON} and @code{EQUIVALENCE} areas such +that the variables and arrays with the widest alignment +guidelines come first. + +For example, on most systems, this would mean placing +@code{COMPLEX(KIND=2)}, @code{REAL(KIND=2)}, and +@code{INTEGER(KIND=2)} entities first, followed by @code{REAL(KIND=1)}, +@code{INTEGER(KIND=1)}, and @code{LOGICAL(KIND=1)} entities, then +@code{INTEGER(KIND=6)} entities, and finally @code{CHARACTER} +and @code{INTEGER(KIND=3)} entities. + +The reason to use such placement is it makes it more likely +that your data will be aligned properly, without requiring +you to do detailed analysis of each aggregate (@code{COMMON} +and @code{EQUIVALENCE}) area. + +Specifically, on systems where the above guidelines are +appropriate, placing @code{CHARACTER} entities before +@code{REAL(KIND=2)} entities can work just as well, +but only if the number of bytes occupied by the @code{CHARACTER} +entities is divisible by the recommended alignment for +@code{REAL(KIND=2)}. + +By ordering the placement of entities in aggregate +areas according to the simple guidelines above, you +avoid having to carefully count the number of bytes +occupied by each entity to determine whether the +actual alignment of each subsequent entity meets the +alignment guidelines for the type of that entity. + +If you don't ensure correct alignment of @code{COMMON} elements, the +compiler may be forced by some systems to violate the Fortran semantics by +adding padding to get @code{DOUBLE PRECISION} data properly aligned. +If the unfortunate practice is employed of overlaying different types of +data in the @code{COMMON} block, the different variants +of this block may become misaligned with respect to each other. +Even if your platform doesn't require strict alignment, +@code{COMMON} should be laid out as above for portability. +(Unfortunately the FORTRAN 77 standard didn't anticipate this +possible requirement, which is compiler-independent on a given platform.) + +@item +@cindex -malign-double option +@cindex options, -malign-double +Use the (x86-specific) @option{-malign-double} option when compiling +programs for the Pentium and Pentium Pro architectures (called 586 +and 686 in the @command{gcc} configuration subsystem). +The warning about this in the @command{gcc} manual isn't +generally relevant to Fortran, +but using it will force @code{COMMON} to be padded if necessary to align +@code{DOUBLE PRECISION} data. + +When @code{DOUBLE PRECISION} data is forcibly aligned +in @code{COMMON} by @command{g77} due to specifying @option{-malign-double}, +@command{g77} issues a warning about the need to +insert padding. + +In this case, each and every program unit that uses +the same @code{COMMON} area +must specify the same layout of variables and their types +for that area +and be compiled with @option{-malign-double} as well. +@command{g77} will issue warnings in each case, +but as long as every program unit using that area +is compiled with the same warnings, +the resulting object files should work when linked together +unless the program makes additional assumptions about +@code{COMMON} area layouts that are outside the scope +of the FORTRAN 77 standard, +or uses @code{EQUIVALENCE} or different layouts +in ways that assume no padding is ever inserted by the compiler. + +@item +Ensure that @file{crt0.o} or @file{crt1.o} +on your system guarantees a 64-bit +aligned stack for @code{main()}. +The recent one from GNU (@code{glibc2}) will do this on x86 systems, +but we don't know of any other x86 setups where it will be right. +Read your system's documentation to determine if +it is appropriate to upgrade to a more recent version +to obtain the optimal alignment. +@end itemize + +Progress is being made on making this work +``out of the box'' on future versions of @command{g77}, +@command{gcc}, and some of the relevant operating systems +(such as GNU/Linux). + +@node Prefer Automatic Uninitialized Variables +@subsection Prefer Automatic Uninitialized Variables + +If you're using @option{-fno-automatic} already, you probably +should change your code to allow compilation with @option{-fautomatic} +(the default), to allow the program to run faster. + +Similarly, you should be able to use @option{-fno-init-local-zero} +(the default) instead of @option{-finit-local-zero}. +This is because it is rare that every variable affected by these +options in a given program actually needs to +be so affected. + +For example, @option{-fno-automatic}, which effectively @code{SAVE}s +every local non-automatic variable and array, affects even things like +@code{DO} iteration +variables, which rarely need to be @code{SAVE}d, and this often reduces +run-time performances. +Similarly, @option{-fno-init-local-zero} forces such +variables to be initialized to zero---when @code{SAVE}d (such as when +@option{-fno-automatic}), this by itself generally affects only +startup time for a program, but when not @code{SAVE}d, +it can slow down the procedure every time it is called. + +@xref{Overly Convenient Options,,Overly Convenient Command-Line Options}, +for information on the @option{-fno-automatic} and +@option{-finit-local-zero} options and how to convert +their use into selective changes in your own code. + +@node Avoid f2c Compatibility +@subsection Avoid f2c Compatibility +@cindex -fno-f2c option +@cindex options, -fno-f2c +@cindex @command{f2c} compatibility +@cindex compatibility, @command{f2c} + +If you aren't linking with any code compiled using +@command{f2c}, try using the @option{-fno-f2c} option when +compiling @emph{all} the code in your program. +(Note that @code{libf2c} is @emph{not} an example of code +that is compiled using @command{f2c}---it is compiled by a C +compiler, typically @command{gcc}.) + +@node Use Submodel Options +@subsection Use Submodel Options +@cindex submodels + +Using an appropriate @option{-m} option to generate specific code for your +CPU may be worthwhile, though it may mean the executable won't run on +other versions of the CPU that don't support the same instruction set. +@xref{Submodel Options,,Hardware Models and Configurations,gcc,Using the +GNU Compiler Collection (GCC)}. For instance on an x86 system the +compiler might have +been built---as shown by @samp{g77 -v}---for the target +@samp{i386-pc-linux-gnu}, i.e.@: an @samp{i386} CPU@. In that case to +generate code best optimized for a Pentium you could use the option +@option{-march=pentium}. + +For recent CPUs that don't have explicit support in the released version +of @command{gcc}, it @emph{might} still be possible to get improvements +with certain @option{-m} options. + +@option{-fomit-frame-pointer} can help performance on x86 systems and +others. It will, however, inhibit debugging on the systems on which it +is not turned on anyway by @option{-O}. + +@node Trouble +@chapter Known Causes of Trouble with GNU Fortran +@cindex bugs, known +@cindex installation trouble +@cindex known causes of trouble + +This section describes known problems that affect users of GNU Fortran. +Most of these are not GNU Fortran bugs per se---if they were, we would +fix them. +But the result for a user might be like the result of a bug. + +Some of these problems are due to bugs in other software, some are +missing features that are too much work to add, and some are places +where people's opinions differ as to what is best. + +(Note that some of this portion of the manual is lifted +directly from the @command{gcc} manual, with minor modifications +to tailor it to users of @command{g77}. +Anytime a bug seems to have more to do with the @command{gcc} +portion of @command{g77}, see +@ref{Trouble,,Known Causes of Trouble with GCC, +gcc,Using the GNU Compiler Collection (GCC)}.) + +@menu +* But-bugs:: Bugs really in other programs or elsewhere. +* Known Bugs:: Bugs known to be in this version of @command{g77}. +* Missing Features:: Features we already know we want to add later. +* Disappointments:: Regrettable things we can't change. +* Non-bugs:: Things we think are right, but some others disagree. +* Warnings and Errors:: Which problems in your code get warnings, + and which get errors. +@end menu + +@node But-bugs +@section Bugs Not In GNU Fortran +@cindex but-bugs + +These are bugs to which the maintainers often have to reply, +``but that isn't a bug in @command{g77}@dots{}''. +Some of these already are fixed in new versions of other +software; some still need to be fixed; some are problems +with how @command{g77} is installed or is being used; +some are the result of bad hardware that causes software +to misbehave in sometimes bizarre ways; +some just cannot be addressed at this time until more +is known about the problem. + +Please don't re-report these bugs to the @command{g77} maintainers---if +you must remind someone how important it is to you that the problem +be fixed, talk to the people responsible for the other products +identified below, but preferably only after you've tried the +latest versions of those products. +The @command{g77} maintainers have their hands full working on +just fixing and improving @command{g77}, without serving as a +clearinghouse for all bugs that happen to affect @command{g77} +users. + +@xref{Collected Fortran Wisdom}, for information on behavior +of Fortran programs, and the programs that compile them, that +might be @emph{thought} to indicate bugs. + +@menu +* Signal 11 and Friends:: Strange behavior by any software. +* Cannot Link Fortran Programs:: Unresolved references. +* Large Common Blocks:: Problems on older GNU/Linux systems. +* Debugger Problems:: When the debugger crashes. +* NeXTStep Problems:: Misbehaving executables. +* Stack Overflow:: More misbehaving executables. +* Nothing Happens:: Less behaving executables. +* Strange Behavior at Run Time:: Executables misbehaving due to + bugs in your program. +* Floating-point Errors:: The results look wrong, but@dots{}. +@end menu + +@node Signal 11 and Friends +@subsection Signal 11 and Friends +@cindex signal 11 +@cindex hardware errors + +A whole variety of strange behaviors can occur when the +software, or the way you are using the software, +stresses the hardware in a way that triggers hardware bugs. +This might seem hard to believe, but it happens frequently +enough that there exist documents explaining in detail +what the various causes of the problems are, what +typical symptoms look like, and so on. + +Generally these problems are referred to in this document +as ``signal 11'' crashes, because the Linux kernel, running +on the most popular hardware (the Intel x86 line), often +stresses the hardware more than other popular operating +systems. +When hardware problems do occur under GNU/Linux on x86 +systems, these often manifest themselves as ``signal 11'' +problems, as illustrated by the following diagnostic: + +@smallexample +sh# @kbd{g77 myprog.f} +gcc: Internal compiler error: program f771 got fatal signal 11 +sh# +@end smallexample + +It is @emph{very} important to remember that the above +message is @emph{not} the only one that indicates a +hardware problem, nor does it always indicate a hardware +problem. + +In particular, on systems other than those running the Linux +kernel, the message might appear somewhat or very different, +as it will if the error manifests itself while running a +program other than the @command{g77} compiler. +For example, +it will appear somewhat different when running your program, +when running Emacs, and so on. + +How to cope with such problems is well beyond the scope +of this manual. + +However, users of Linux-based systems (such as GNU/Linux) +should review @uref{http://www.bitwizard.nl/sig11/}, a source +of detailed information on diagnosing hardware problems, +by recognizing their common symptoms. + +Users of other operating systems and hardware might +find this reference useful as well. +If you know of similar material for another hardware/software +combination, please let us know so we can consider including +a reference to it in future versions of this manual. + +@node Cannot Link Fortran Programs +@subsection Cannot Link Fortran Programs +@cindex unresolved reference (various) +@cindex linking error for user code +@cindex code, user +@cindex @command{ld}, error linking user code +@cindex @command{ld}, can't find strange names +On some systems, perhaps just those with out-of-date (shared?) +libraries, unresolved-reference errors happen when linking @command{g77}-compiled +programs (which should be done using @command{g77}). + +If this happens to you, try appending @option{-lc} to the command you +use to link the program, e.g. @samp{g77 foo.f -lc}. +@command{g77} already specifies @samp{-lg2c -lm} when it calls the linker, +but it cannot also specify @option{-lc} because not all systems have a +file named @file{libc.a}. + +It is unclear at this point whether there are legitimately installed +systems where @samp{-lg2c -lm} is insufficient to resolve code produced +by @command{g77}. + +@cindex undefined reference (_main) +@cindex linking error, user code +@cindex @command{ld}, error linking user code +@cindex code, user +@cindex @command{ld}, can't find @samp{_main} +If your program doesn't link due to unresolved references to names +like @samp{_main}, make sure you're using the @command{g77} command to do the +link, since this command ensures that the necessary libraries are +loaded by specifying @samp{-lg2c -lm} when it invokes the @command{gcc} +command to do the actual link. +(Use the @option{-v} option to discover +more about what actually happens when you use the @command{g77} and @command{gcc} +commands.) + +Also, try specifying @option{-lc} as the last item on the @command{g77} +command line, in case that helps. + +@node Large Common Blocks +@subsection Large Common Blocks +@cindex common blocks, large +@cindex large common blocks +@cindex linking, errors +@cindex @command{ld}, errors +@cindex errors, linker +On some older GNU/Linux systems, programs with common blocks larger +than 16MB cannot be linked without some kind of error +message being produced. + +This is a bug in older versions of @command{ld}, fixed in +more recent versions of @code{binutils}, such as version 2.6. + +@node Debugger Problems +@subsection Debugger Problems +@cindex @command{gdb}, support +@cindex support, @command{gdb} +There are some known problems when using @command{gdb} on code +compiled by @command{g77}. +Inadequate investigation as of the release of 0.5.16 results in not +knowing which products are the culprit, but @file{gdb-4.14} definitely +crashes when, for example, an attempt is made to print the contents +of a @code{COMPLEX(KIND=2)} dummy array, on at least some GNU/Linux +machines, plus some others. +Attempts to access assumed-size arrays are +also known to crash recent versions of @command{gdb}. +(@command{gdb}'s Fortran support was done for a different compiler +and isn't properly compatible with @command{g77}.) + +@node NeXTStep Problems +@subsection NeXTStep Problems +@cindex NeXTStep problems +@cindex bus error +@cindex segmentation violation +Developers of Fortran code on NeXTStep (all architectures) have to +watch out for the following problem when writing programs with +large, statically allocated (i.e. non-stack based) data structures +(common blocks, saved arrays). + +Due to the way the native loader (@file{/bin/ld}) lays out +data structures in virtual memory, it is very easy to create an +executable wherein the @samp{__DATA} segment overlaps (has addresses in +common) with the @samp{UNIX STACK} segment. + +This leads to all sorts of trouble, from the executable simply not +executing, to bus errors. +The NeXTStep command line tool @command{ebadexec} points to +the problem as follows: + +@smallexample +% @kbd{/bin/ebadexec a.out} +/bin/ebadexec: __LINKEDIT segment (truncated address = 0x3de000 +rounded size = 0x2a000) of executable file: a.out overlaps with UNIX +STACK segment (truncated address = 0x400000 rounded size = +0x3c00000) of executable file: a.out +@end smallexample + +(In the above case, it is the @samp{__LINKEDIT} segment that overlaps the +stack segment.) + +This can be cured by assigning the @samp{__DATA} segment +(virtual) addresses beyond the stack segment. +A conservative +estimate for this is from address 6000000 (hexadecimal) onwards---this +has always worked for me [Toon Moene]: + +@smallexample +% @kbd{g77 -segaddr __DATA 6000000 test.f} +% @kbd{ebadexec a.out} +ebadexec: file: a.out appears to be executable +% +@end smallexample + +Browsing through @file{@value{path-g77}/Makefile.in}, +you will find that the @code{f771} program itself also has to be +linked with these flags---it has large statically allocated +data structures. +(Version 0.5.18 reduces this somewhat, but probably +not enough.) + +(The above item was contributed by Toon Moene +(@email{toon@@moene.indiv.nluug.nl}).) + +@node Stack Overflow +@subsection Stack Overflow +@cindex stack, overflow +@cindex segmentation violation +@command{g77} code might fail at runtime (probably with a ``segmentation +violation'') due to overflowing the stack. +This happens most often on systems with an environment +that provides substantially more heap space (for use +when arbitrarily allocating and freeing memory) than stack +space. + +Often this can be cured by +increasing or removing your shell's limit on stack usage, typically +using @kbd{limit stacksize} (in @command{csh} and derivatives) or +@kbd{ulimit -s} (in @command{sh} and derivatives). + +Increasing the allowed stack size might, however, require +changing some operating system or system configuration parameters. + +You might be able to work around the problem by compiling with the +@option{-fno-automatic} option to reduce stack usage, probably at the +expense of speed. + +@command{g77}, on most machines, puts many variables and arrays on the stack +where possible, and can be configured (by changing +@code{FFECOM_sizeMAXSTACKITEM} in @file{@value{path-g77}/com.c}) to force +smaller-sized entities into static storage (saving +on stack space) or permit larger-sized entities to be put on the +stack (which can improve run-time performance, as it presents +more opportunities for the GBE to optimize the generated code). + +@emph{Note:} Putting more variables and arrays on the stack +might cause problems due to system-dependent limits on stack size. +Also, the value of @code{FFECOM_sizeMAXSTACKITEM} has no +effect on automatic variables and arrays. +@xref{But-bugs}, for more information. +@emph{Note:} While @code{libg2c} places a limit on the range +of Fortran file-unit numbers, the underlying library and operating +system might impose different kinds of limits. +For example, some systems limit the number of files simultaneously +open by a running program. +Information on how to increase these limits should be found +in your system's documentation. + +@cindex automatic arrays +@cindex arrays, automatic +However, if your program uses large automatic arrays +(for example, has declarations like @samp{REAL A(N)} where +@samp{A} is a local array and @samp{N} is a dummy or +@code{COMMON} variable that can have a large value), +neither use of @option{-fno-automatic}, +nor changing the cut-off point for @command{g77} for using the stack, +will solve the problem by changing the placement of these +large arrays, as they are @emph{necessarily} automatic. + +@command{g77} currently provides no means to specify that +automatic arrays are to be allocated on the heap instead +of the stack. +So, other than increasing the stack size, your best bet is to +change your source code to avoid large automatic arrays. +Methods for doing this currently are outside the scope of +this document. + +(@emph{Note:} If your system puts stack and heap space in the +same memory area, such that they are effectively combined, then +a stack overflow probably indicates a program that is either +simply too large for the system, or buggy.) + +@node Nothing Happens +@subsection Nothing Happens +@cindex nothing happens +@cindex naming programs +@cindex @command{test} programs +@cindex programs, @command{test} +It is occasionally reported that a ``simple'' program, +such as a ``Hello, World!'' program, does nothing when +it is run, even though the compiler reported no errors, +despite the program containing nothing other than a +simple @code{PRINT} statement. + +This most often happens because the program has been +compiled and linked on a UNIX system and named @command{test}, +though other names can lead to similarly unexpected +run-time behavior on various systems. + +Essentially this problem boils down to giving +your program a name that is already known to +the shell you are using to identify some other program, +which the shell continues to execute instead of your +program when you invoke it via, for example: + +@smallexample +sh# @kbd{test} +sh# +@end smallexample + +Under UNIX and many other system, a simple command name +invokes a searching mechanism that might well not choose +the program located in the current working directory if +there is another alternative (such as the @command{test} +command commonly installed on UNIX systems). + +The reliable way to invoke a program you just linked in +the current directory under UNIX is to specify it using +an explicit pathname, as in: + +@smallexample +sh# @kbd{./test} + Hello, World! +sh# +@end smallexample + +Users who encounter this problem should take the time to +read up on how their shell searches for commands, how to +set their search path, and so on. +The relevant UNIX commands to learn about include +@command{man}, @command{info} (on GNU systems), @command{setenv} (or +@command{set} and @command{env}), @command{which}, and @command{find}. + +@node Strange Behavior at Run Time +@subsection Strange Behavior at Run Time +@cindex segmentation violation +@cindex bus error +@cindex overwritten data +@cindex data, overwritten +@command{g77} code might fail at runtime with ``segmentation violation'', +``bus error'', or even something as subtle as a procedure call +overwriting a variable or array element that it is not supposed +to touch. + +These can be symptoms of a wide variety of actual bugs that +occurred earlier during the program's run, but manifested +themselves as @emph{visible} problems some time later. + +Overflowing the bounds of an array---usually by writing beyond +the end of it---is one of two kinds of bug that often occurs +in Fortran code. +(Compile your code with the @option{-fbounds-check} option +to catch many of these kinds of errors at program run time.) + +The other kind of bug is a mismatch between the actual arguments +passed to a procedure and the dummy arguments as declared by that +procedure. + +Both of these kinds of bugs, and some others as well, can be +difficult to track down, because the bug can change its behavior, +or even appear to not occur, when using a debugger. + +That is, these bugs can be quite sensitive to data, including +data representing the placement of other data in memory (that is, +pointers, such as the placement of stack frames in memory). + +@command{g77} now offers the +ability to catch and report some of these problems at compile, link, or +run time, such as by generating code to detect references to +beyond the bounds of most arrays (except assumed-size arrays), +and checking for agreement between calling and called procedures. +Future improvements are likely to be made in the procedure-mismatch area, +at least. + +In the meantime, finding and fixing the programming +bugs that lead to these behaviors is, ultimately, the user's +responsibility, as difficult as that task can sometimes be. + +@cindex infinite spaces printed +@cindex space, endless printing of +@cindex libc, non-ANSI or non-default +@cindex C library +@cindex linking against non-standard library +@cindex Solaris +One runtime problem that has been observed might have a simple solution. +If a formatted @code{WRITE} produces an endless stream of spaces, check +that your program is linked against the correct version of the C library. +The configuration process takes care to account for your +system's normal @file{libc} not being ANSI-standard, which will +otherwise cause this behavior. +If your system's default library is +ANSI-standard and you subsequently link against a non-ANSI one, there +might be problems such as this one. + +Specifically, on Solaris2 systems, +avoid picking up the @code{BSD} library from @file{/usr/ucblib}. + +@node Floating-point Errors +@subsection Floating-point Errors +@cindex floating-point errors +@cindex rounding errors +@cindex inconsistent floating-point results +@cindex results, inconsistent +Some programs appear to produce inconsistent floating-point +results compiled by @command{g77} versus by other compilers. + +Often the reason for this behavior is the fact that floating-point +values are represented on almost all Fortran systems by +@emph{approximations}, and these approximations are inexact +even for apparently simple values like 0.1, 0.2, 0.3, 0.4, 0.6, +0.7, 0.8, 0.9, 1.1, and so on. +Most Fortran systems, including all current ports of @command{g77}, +use binary arithmetic to represent these approximations. + +Therefore, the exact value of any floating-point approximation +as manipulated by @command{g77}-compiled code is representable by +adding some combination of the values 1.0, 0.5, 0.25, 0.125, and +so on (just keep dividing by two) through the precision of the +fraction (typically around 23 bits for @code{REAL(KIND=1)}, 52 for +@code{REAL(KIND=2)}), then multiplying the sum by a integral +power of two (in Fortran, by @samp{2**N}) that typically is between +-127 and +128 for @code{REAL(KIND=1)} and -1023 and +1024 for +@code{REAL(KIND=2)}, then multiplying by -1 if the number +is negative. + +So, a value like 0.2 is exactly represented in decimal---since +it is a fraction, @samp{2/10}, with a denominator that is compatible +with the base of the number system (base 10). +However, @samp{2/10} cannot be represented by any finite number +of sums of any of 1.0, 0.5, 0.25, and so on, so 0.2 cannot +be exactly represented in binary notation. + +(On the other hand, decimal notation can represent any binary +number in a finite number of digits. +Decimal notation cannot do so with ternary, or base-3, +notation, which would represent floating-point numbers as +sums of any of @samp{1/1}, @samp{1/3}, @samp{1/9}, and so on. +After all, no finite number of decimal digits can exactly +represent @samp{1/3}. +Fortunately, few systems use ternary notation.) + +Moreover, differences in the way run-time I/O libraries convert +between these approximations and the decimal representation often +used by programmers and the programs they write can result in +apparent differences between results that do not actually exist, +or exist to such a small degree that they usually are not worth +worrying about. + +For example, consider the following program: + +@smallexample +PRINT *, 0.2 +END +@end smallexample + +When compiled by @command{g77}, the above program might output +@samp{0.20000003}, while another compiler might produce a +executable that outputs @samp{0.2}. + +This particular difference is due to the fact that, currently, +conversion of floating-point values by the @code{libg2c} library, +used by @command{g77}, handles only double-precision values. + +Since @samp{0.2} in the program is a single-precision value, it +is converted to double precision (still in binary notation) +before being converted back to decimal. +The conversion to binary appends @emph{binary} zero digits to the +original value---which, again, is an inexact approximation of +0.2---resulting in an approximation that is much less exact +than is connoted by the use of double precision. + +(The appending of binary zero digits has essentially the same +effect as taking a particular decimal approximation of +@samp{1/3}, such as @samp{0.3333333}, and appending decimal +zeros to it, producing @samp{0.33333330000000000}. +Treating the resulting decimal approximation as if it really +had 18 or so digits of valid precision would make it seem +a very poor approximation of @samp{1/3}.) + +As a result of converting the single-precision approximation +to double precision by appending binary zeros, the conversion +of the resulting double-precision +value to decimal produces what looks like an incorrect +result, when in fact the result is @emph{inexact}, and +is probably no less inaccurate or imprecise an approximation +of 0.2 than is produced by other compilers that happen to output +the converted value as ``exactly'' @samp{0.2}. +(Some compilers behave in a way that can make them appear +to retain more accuracy across a conversion of a single-precision +constant to double precision. +@xref{Context-Sensitive Constants}, to see why +this practice is illusory and even dangerous.) + +Note that a more exact approximation of the constant is +computed when the program is changed to specify a +double-precision constant: + +@smallexample +PRINT *, 0.2D0 +END +@end smallexample + +Future versions of @command{g77} and/or @code{libg2c} might convert +single-precision values directly to decimal, +instead of converting them to double precision first. +This would tend to result in output that is more consistent +with that produced by some other Fortran implementations. + +A useful source of information on floating-point computation is David +Goldberg, `What Every Computer Scientist Should Know About +Floating-Point Arithmetic', Computing Surveys, 23, March 1991, pp.@: +5-48. +An online version is available at +@uref{http://docs.sun.com/}. + +Information related to the IEEE 754 floating-point standard can be found +at @uref{http://grouper.ieee.org/groups/754/} and +@uref{http://http.cs.berkeley.edu/%7Ewkahan/ieee754status/}; +see also slides from the short course referenced from +@uref{http://http.cs.berkeley.edu/%7Efateman/}. + +The supplement to the PostScript-formatted Goldberg document, +referenced above, is available in HTML format. +See `Differences Among IEEE 754 Implementations' by Doug Priest. +This document explores some of the issues surrounding computing +of extended (80-bit) results on processors such as the x86, +especially when those results are arbitrarily truncated +to 32-bit or 64-bit values by the compiler +as ``spills''. + +@cindex spills of floating-point results +@cindex 80-bit spills +@cindex truncation, of floating-point values +(@emph{Note:} @command{g77} specifically, and @command{gcc} generally, +does arbitrarily truncate 80-bit results during spills +as of this writing. +It is not yet clear whether a future version of +the GNU compiler suite will offer 80-bit spills +as an option, or perhaps even as the default behavior.) + +@c xref would be different between editions: +The GNU C library provides routines for controlling the FPU, and other +documentation about this. + +@xref{Floating-point precision}, regarding IEEE 754 conformance. + +@include bugs.texi + +@node Missing Features +@section Missing Features + +This section lists features we know are missing from @command{g77}, +and which we want to add someday. +(There is no priority implied in the ordering below.) + +@menu +GNU Fortran language: +* Better Source Model:: +* Fortran 90 Support:: +* Intrinsics in PARAMETER Statements:: +* Arbitrary Concatenation:: +* SELECT CASE on CHARACTER Type:: +* RECURSIVE Keyword:: +* Popular Non-standard Types:: +* Full Support for Compiler Types:: +* Array Bounds Expressions:: +* POINTER Statements:: +* Sensible Non-standard Constructs:: +* READONLY Keyword:: +* FLUSH Statement:: +* Expressions in FORMAT Statements:: +* Explicit Assembler Code:: +* Q Edit Descriptor:: + +GNU Fortran dialects: +* Old-style PARAMETER Statements:: +* TYPE and ACCEPT I/O Statements:: +* STRUCTURE UNION RECORD MAP:: +* OPEN CLOSE and INQUIRE Keywords:: +* ENCODE and DECODE:: +* AUTOMATIC Statement:: +* Suppressing Space Padding:: +* Fortran Preprocessor:: +* Bit Operations on Floating-point Data:: +* Really Ugly Character Assignments:: + +New facilities: +* POSIX Standard:: +* Floating-point Exception Handling:: +* Nonportable Conversions:: +* Large Automatic Arrays:: +* Support for Threads:: +* Increasing Precision/Range:: +* Enabling Debug Lines:: + +Better diagnostics: +* Better Warnings:: +* Gracefully Handle Sensible Bad Code:: +* Non-standard Conversions:: +* Non-standard Intrinsics:: +* Modifying DO Variable:: +* Better Pedantic Compilation:: +* Warn About Implicit Conversions:: +* Invalid Use of Hollerith Constant:: +* Dummy Array Without Dimensioning Dummy:: +* Invalid FORMAT Specifiers:: +* Ambiguous Dialects:: +* Unused Labels:: +* Informational Messages:: + +Run-time facilities: +* Uninitialized Variables at Run Time:: +* Portable Unformatted Files:: +* Better List-directed I/O:: +* Default to Console I/O:: + +Debugging: +* Labels Visible to Debugger:: +@end menu + +@node Better Source Model +@subsection Better Source Model + +@command{g77} needs to provide, as the default source-line model, +a ``pure visual'' mode, where +the interpretation of a source program in this mode can be accurately +determined by a user looking at a traditionally displayed rendition +of the program (assuming the user knows whether the program is fixed +or free form). + +The design should assume the user cannot tell tabs from spaces +and cannot see trailing spaces on lines, but has canonical tab stops +and, for fixed-form source, has the ability to always know exactly +where column 72 is (since the Fortran standard itself requires +this for fixed-form source). + +This would change the default treatment of fixed-form source +to not treat lines with tabs as if they were infinitely long---instead, +they would end at column 72 just as if the tabs were replaced +by spaces in the canonical way. + +As part of this, provide common alternate models (Digital, @command{f2c}, +and so on) via command-line options. +This includes allowing arbitrarily long +lines for free-form source as well as fixed-form source and providing +various limits and diagnostics as appropriate. + +@cindex sequence numbers +@cindex columns 73 through 80 +Also, @command{g77} should offer, perhaps even default to, warnings +when characters beyond the last valid column are anything other +than spaces. +This would mean code with ``sequence numbers'' in columns 73 through 80 +would be rejected, and there's a lot of that kind of code around, +but one of the most frequent bugs encountered by new users is +accidentally writing fixed-form source code into and beyond +column 73. +So, maybe the users of old code would be able to more easily handle +having to specify, say, a @option{-Wno-col73to80} option. + +@node Fortran 90 Support +@subsection Fortran 90 Support +@cindex Fortran 90, support +@cindex support, Fortran 90 + +@command{g77} does not support many of the features that +distinguish Fortran 90 (and, now, Fortran 95) from +ANSI FORTRAN 77. + +Some Fortran 90 features are supported, because they +make sense to offer even to die-hard users of F77. +For example, many of them codify various ways F77 has +been extended to meet users' needs during its tenure, +so @command{g77} might as well offer them as the primary +way to meet those same needs, even if it offers compatibility +with one or more of the ways those needs were met +by other F77 compilers in the industry. + +Still, many important F90 features are not supported, +because no attempt has been made to research each and +every feature and assess its viability in @command{g77}. +In the meantime, users who need those features must +use Fortran 90 compilers anyway, and the best approach +to adding some F90 features to GNU Fortran might well be +to fund a comprehensive project to create GNU Fortran 95. + +@node Intrinsics in PARAMETER Statements +@subsection Intrinsics in @code{PARAMETER} Statements +@cindex PARAMETER statement +@cindex statements, PARAMETER + +@command{g77} doesn't allow intrinsics in @code{PARAMETER} statements. + +Related to this, @command{g77} doesn't allow non-integral +exponentiation in @code{PARAMETER} statements, such as +@samp{PARAMETER (R=2**.25)}. +It is unlikely @command{g77} will ever support this feature, +as doing it properly requires complete emulation of +a target computer's floating-point facilities when +building @command{g77} as a cross-compiler. +But, if the @command{gcc} back end is enhanced to provide +such a facility, @command{g77} will likely use that facility +in implementing this feature soon afterwards. + +@node Arbitrary Concatenation +@subsection Arbitrary Concatenation +@cindex concatenation +@cindex CHARACTER*(*) +@cindex run-time, dynamic allocation + +@command{g77} doesn't support arbitrary operands for concatenation +in contexts where run-time allocation is required. +For example: + +@smallexample +SUBROUTINE X(A) +CHARACTER*(*) A +CALL FOO(A // 'suffix') +@end smallexample + +@node SELECT CASE on CHARACTER Type +@subsection @code{SELECT CASE} on @code{CHARACTER} Type + +Character-type selector/cases for @code{SELECT CASE} currently +are not supported. + +@node RECURSIVE Keyword +@subsection @code{RECURSIVE} Keyword +@cindex RECURSIVE keyword +@cindex keywords, RECURSIVE +@cindex recursion, lack of +@cindex lack of recursion + +@command{g77} doesn't support the @code{RECURSIVE} keyword that +F90 compilers do. +Nor does it provide any means for compiling procedures +designed to do recursion. + +All recursive code can be rewritten to not use recursion, +but the result is not pretty. + +@node Increasing Precision/Range +@subsection Increasing Precision/Range +@cindex -r8 +@cindex -qrealsize=8 +@cindex -i8 +@cindex f2c +@cindex increasing precision +@cindex precision, increasing +@cindex increasing range +@cindex range, increasing +@cindex Toolpack +@cindex Netlib + +Some compilers, such as @command{f2c}, have an option (@option{-r8}, +@option{-qrealsize=8} or +similar) that provides automatic treatment of @code{REAL} +entities such that they have twice the storage size, and +a corresponding increase in the range and precision, of what +would normally be the @code{REAL(KIND=1)} (default @code{REAL}) type. +(This affects @code{COMPLEX} the same way.) + +They also typically offer another option (@option{-i8}) to increase +@code{INTEGER} entities so they are twice as large +(with roughly twice as much range). + +(There are potential pitfalls in using these options.) + +@command{g77} does not yet offer any option that performs these +kinds of transformations. +Part of the problem is the lack of detailed specifications regarding +exactly how these options affect the interpretation of constants, +intrinsics, and so on. + +Until @command{g77} addresses this need, programmers could improve +the portability of their code by modifying it to not require +compile-time options to produce correct results. +Some free tools are available which may help, specifically +in Toolpack (which one would expect to be sound) and the @file{fortran} +section of the Netlib repository. + +Use of preprocessors can provide a fairly portable means +to work around the lack of widely portable methods in the Fortran +language itself (though increasing acceptance of Fortran 90 would +alleviate this problem). + +@node Popular Non-standard Types +@subsection Popular Non-standard Types +@cindex @code{INTEGER*2} support +@cindex types, @code{INTEGER*2} +@cindex @code{LOGICAL*1} support +@cindex types, @code{LOGICAL*1} + +@command{g77} doesn't fully support @code{INTEGER*2}, @code{LOGICAL*1}, +and similar. +In the meantime, version 0.5.18 provides rudimentary support +for them. + +@node Full Support for Compiler Types +@subsection Full Support for Compiler Types + +@cindex @code{REAL*16} support +@cindex types, @code{REAL*16} +@cindex @code{INTEGER*8} support +@cindex types, @code{INTEGER*8} +@command{g77} doesn't support @code{INTEGER}, @code{REAL}, and @code{COMPLEX} equivalents +for @emph{all} applicable back-end-supported types (@code{char}, @code{short int}, +@code{int}, @code{long int}, @code{long long int}, and @code{long double}). +This means providing intrinsic support, and maybe constant +support (using F90 syntax) as well, and, for most +machines will result in automatic support of @code{INTEGER*1}, +@code{INTEGER*2}, @code{INTEGER*8}, maybe even @code{REAL*16}, +and so on. + +@node Array Bounds Expressions +@subsection Array Bounds Expressions +@cindex array elements, in adjustable array bounds +@cindex function references, in adjustable array bounds +@cindex array bounds, adjustable +@cindex @code{DIMENSION} statement +@cindex statements, @code{DIMENSION} + +@command{g77} doesn't support more general expressions to dimension +arrays, such as array element references, function +references, etc. + +For example, @command{g77} currently does not accept the following: + +@smallexample +SUBROUTINE X(M, N) +INTEGER N(10), M(N(2), N(1)) +@end smallexample + +@node POINTER Statements +@subsection POINTER Statements +@cindex POINTER statement +@cindex statements, POINTER +@cindex Cray pointers + +@command{g77} doesn't support pointers or allocatable objects +(other than automatic arrays). +This set of features is +probably considered just behind intrinsics +in @code{PARAMETER} statements on the list of large, +important things to add to @command{g77}. + +In the meantime, consider using the @code{INTEGER(KIND=7)} +declaration to specify that a variable must be +able to hold a pointer. +This construct is not portable to other non-GNU compilers, +but it is portable to all machines GNU Fortran supports +when @command{g77} is used. + +@xref{Functions and Subroutines}, for information on +@code{%VAL()}, @code{%REF()}, and @code{%DESCR()} +constructs, which are useful for passing pointers to +procedures written in languages other than Fortran. + +@node Sensible Non-standard Constructs +@subsection Sensible Non-standard Constructs + +@command{g77} rejects things other compilers accept, +like @samp{INTRINSIC SQRT,SQRT}. +As time permits in the future, some of these things that are easy for +humans to read and write and unlikely to be intended to mean something +else will be accepted by @command{g77} (though @option{-fpedantic} should +trigger warnings about such non-standard constructs). + +Until @command{g77} no longer gratuitously rejects sensible code, +you might as well fix your code +to be more standard-conforming and portable. + +The kind of case that is important to except from the +recommendation to change your code is one where following +good coding rules would force you to write non-standard +code that nevertheless has a clear meaning. + +For example, when writing an @code{INCLUDE} file that +defines a common block, it might be appropriate to +include a @code{SAVE} statement for the common block +(such as @samp{SAVE /CBLOCK/}), so that variables +defined in the common block retain their values even +when all procedures declaring the common block become +inactive (return to their callers). + +However, putting @code{SAVE} statements in an @code{INCLUDE} +file would prevent otherwise standard-conforming code +from also specifying the @code{SAVE} statement, by itself, +to indicate that all local variables and arrays are to +have the @code{SAVE} attribute. + +For this reason, @command{g77} already has been changed to +allow this combination, because although the general +problem of gratuitously rejecting unambiguous and +``safe'' constructs still exists in @command{g77}, this +particular construct was deemed useful enough that +it was worth fixing @command{g77} for just this case. + +So, while there is no need to change your code +to avoid using this particular construct, there +might be other, equally appropriate but non-standard +constructs, that you shouldn't have to stop using +just because @command{g77} (or any other compiler) +gratuitously rejects it. + +Until the general problem is solved, if you have +any such construct you believe is worthwhile +using (e.g. not just an arbitrary, redundant +specification of an attribute), please submit a +bug report with an explanation, so we can consider +fixing @command{g77} just for cases like yours. + +@node READONLY Keyword +@subsection @code{READONLY} Keyword +@cindex READONLY + +Support for @code{READONLY}, in @code{OPEN} statements, +requires @code{libg2c} support, +to make sure that @samp{CLOSE(@dots{},STATUS='DELETE')} +does not delete a file opened on a unit +with the @code{READONLY} keyword, +and perhaps to trigger a fatal diagnostic +if a @code{WRITE} or @code{PRINT} +to such a unit is attempted. + +@emph{Note:} It is not sufficient for @command{g77} and @code{libg2c} +(its version of @code{libf2c}) +to assume that @code{READONLY} does not need some kind of explicit support +at run time, +due to UNIX systems not (generally) needing it. +@command{g77} is not just a UNIX-based compiler! + +Further, mounting of non-UNIX filesystems on UNIX systems +(such as via NFS) +might require proper @code{READONLY} support. + +@cindex SHARED +(Similar issues might be involved with supporting the @code{SHARED} +keyword.) + +@node FLUSH Statement +@subsection @code{FLUSH} Statement + +@command{g77} could perhaps use a @code{FLUSH} statement that +does what @samp{CALL FLUSH} does, +but that supports @samp{*} as the unit designator (same unit as for +@code{PRINT}) and accepts @code{ERR=} and/or @code{IOSTAT=} +specifiers. + +@node Expressions in FORMAT Statements +@subsection Expressions in @code{FORMAT} Statements +@cindex FORMAT statement +@cindex statements, FORMAT + +@command{g77} doesn't support @samp{FORMAT(I<J>)} and the like. +Supporting this requires a significant redesign or replacement +of @code{libg2c}. + +However, @command{g77} does support +this construct when the expression is constant +(as of version 0.5.22). +For example: + +@smallexample + PARAMETER (IWIDTH = 12) +10 FORMAT (I<IWIDTH>) +@end smallexample + +Otherwise, at least for output (@code{PRINT} and +@code{WRITE}), Fortran code making use of this feature can +be rewritten to avoid it by constructing the @code{FORMAT} +string in a @code{CHARACTER} variable or array, then +using that variable or array in place of the @code{FORMAT} +statement label to do the original @code{PRINT} or @code{WRITE}. + +Many uses of this feature on input can be rewritten this way +as well, but not all can. +For example, this can be rewritten: + +@smallexample + READ 20, I +20 FORMAT (I<J>) +@end smallexample + +However, this cannot, in general, be rewritten, especially +when @code{ERR=} and @code{END=} constructs are employed: + +@smallexample + READ 30, J, I +30 FORMAT (I<J>) +@end smallexample + +@node Explicit Assembler Code +@subsection Explicit Assembler Code + +@command{g77} needs to provide some way, a la @command{gcc}, for @command{g77} +code to specify explicit assembler code. + +@node Q Edit Descriptor +@subsection Q Edit Descriptor +@cindex FORMAT statement +@cindex Q edit descriptor +@cindex edit descriptor, Q + +The @code{Q} edit descriptor in @code{FORMAT}s isn't supported. +(This is meant to get the number of characters remaining in an input record.) +Supporting this requires a significant redesign or replacement +of @code{libg2c}. + +A workaround might be using internal I/O or the stream-based intrinsics. +@xref{FGetC Intrinsic (subroutine)}. + +@node Old-style PARAMETER Statements +@subsection Old-style PARAMETER Statements +@cindex PARAMETER statement +@cindex statements, PARAMETER + +@command{g77} doesn't accept @samp{PARAMETER I=1}. +Supporting this obsolete form of +the @code{PARAMETER} statement would not be particularly hard, as most of the +parsing code is already in place and working. + +Until time/money is +spent implementing it, you might as well fix your code to use the +standard form, @samp{PARAMETER (I=1)} (possibly needing +@samp{INTEGER I} preceding the @code{PARAMETER} statement as well, +otherwise, in the obsolete form of @code{PARAMETER}, the +type of the variable is set from the type of the constant being +assigned to it). + +@node TYPE and ACCEPT I/O Statements +@subsection @code{TYPE} and @code{ACCEPT} I/O Statements +@cindex TYPE statement +@cindex statements, TYPE +@cindex ACCEPT statement +@cindex statements, ACCEPT + +@command{g77} doesn't support the I/O statements @code{TYPE} and +@code{ACCEPT}. +These are common extensions that should be easy to support, +but also are fairly easy to work around in user code. + +Generally, any @samp{TYPE fmt,list} I/O statement can be replaced +by @samp{PRINT fmt,list}. +And, any @samp{ACCEPT fmt,list} statement can be +replaced by @samp{READ fmt,list}. + +@node STRUCTURE UNION RECORD MAP +@subsection @code{STRUCTURE}, @code{UNION}, @code{RECORD}, @code{MAP} +@cindex STRUCTURE statement +@cindex statements, STRUCTURE +@cindex UNION statement +@cindex statements, UNION +@cindex RECORD statement +@cindex statements, RECORD +@cindex MAP statement +@cindex statements, MAP + +@command{g77} doesn't support @code{STRUCTURE}, @code{UNION}, @code{RECORD}, +@code{MAP}. +This set of extensions is quite a bit +lower on the list of large, important things to add to @command{g77}, partly +because it requires a great deal of work either upgrading or +replacing @code{libg2c}. + +@node OPEN CLOSE and INQUIRE Keywords +@subsection @code{OPEN}, @code{CLOSE}, and @code{INQUIRE} Keywords +@cindex disposition of files +@cindex OPEN statement +@cindex statements, OPEN +@cindex CLOSE statement +@cindex statements, CLOSE +@cindex INQUIRE statement +@cindex statements, INQUIRE + +@command{g77} doesn't have support for keywords such as @code{DISP='DELETE'} in +the @code{OPEN}, @code{CLOSE}, and @code{INQUIRE} statements. +These extensions are easy to add to @command{g77} itself, but +require much more work on @code{libg2c}. + +@cindex FORM='PRINT' +@cindex ANS carriage control +@cindex carriage control +@pindex asa +@pindex fpr +@command{g77} doesn't support @code{FORM='PRINT'} or an equivalent to +translate the traditional `carriage control' characters in column 1 of +output to use backspaces, carriage returns and the like. However +programs exist to translate them in output files (or standard output). +These are typically called either @command{fpr} or @command{asa}. You can get +a version of @command{asa} from +@uref{ftp://sunsite.unc.edu/pub/Linux/devel/lang/fortran} for GNU +systems which will probably build easily on other systems. +Alternatively, @command{fpr} is in BSD distributions in various archive +sites. + +@c (Can both programs can be used in a pipeline, +@c with a named input file, +@c and/or with a named output file???) + +@node ENCODE and DECODE +@subsection @code{ENCODE} and @code{DECODE} +@cindex ENCODE statement +@cindex statements, ENCODE +@cindex DECODE statement +@cindex statements, DECODE + +@command{g77} doesn't support @code{ENCODE} or @code{DECODE}. + +These statements are best replaced by READ and WRITE statements +involving internal files (CHARACTER variables and arrays). + +For example, replace a code fragment like + +@smallexample + INTEGER*1 LINE(80) +@dots{} + DECODE (80, 9000, LINE) A, B, C +@dots{} +9000 FORMAT (1X, 3(F10.5)) +@end smallexample + +@noindent +with: + +@smallexample + CHARACTER*80 LINE +@dots{} + READ (UNIT=LINE, FMT=9000) A, B, C +@dots{} +9000 FORMAT (1X, 3(F10.5)) +@end smallexample + +Similarly, replace a code fragment like + +@smallexample + INTEGER*1 LINE(80) +@dots{} + ENCODE (80, 9000, LINE) A, B, C +@dots{} +9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) +@end smallexample + +@noindent +with: + +@smallexample + CHARACTER*80 LINE +@dots{} + WRITE (UNIT=LINE, FMT=9000) A, B, C +@dots{} +9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) +@end smallexample + +It is entirely possible that @code{ENCODE} and @code{DECODE} will +be supported by a future version of @command{g77}. + +@node AUTOMATIC Statement +@subsection @code{AUTOMATIC} Statement +@cindex @code{AUTOMATIC} statement +@cindex statements, @code{AUTOMATIC} +@cindex automatic variables +@cindex variables, automatic + +@command{g77} doesn't support the @code{AUTOMATIC} statement that +@command{f2c} does. + +@code{AUTOMATIC} would identify a variable or array +as not being @code{SAVE}'d, which is normally the default, +but which would be especially useful for code that, @emph{generally}, +needed to be compiled with the @option{-fno-automatic} option. + +@code{AUTOMATIC} also would serve as a hint to the compiler that placing +the variable or array---even a very large array--on the stack is acceptable. + +@code{AUTOMATIC} would not, by itself, designate the containing procedure +as recursive. + +@code{AUTOMATIC} should work syntactically like @code{SAVE}, +in that @code{AUTOMATIC} with no variables listed should apply to +all pertinent variables and arrays +(which would not include common blocks or their members). + +Variables and arrays denoted as @code{AUTOMATIC} +would not be permitted to be initialized via @code{DATA} +or other specification of any initial values, +requiring explicit initialization, +such as via assignment statements. + +@cindex UNSAVE +@cindex STATIC +Perhaps @code{UNSAVE} and @code{STATIC}, +as strict semantic opposites to @code{SAVE} and @code{AUTOMATIC}, +should be provided as well. + +@node Suppressing Space Padding +@subsection Suppressing Space Padding of Source Lines + +@command{g77} should offer VXT-Fortran-style suppression of virtual +spaces at the end of a source line +if an appropriate command-line option is specified. + +This affects cases where +a character constant is continued onto the next line in a fixed-form +source file, as in the following example: + +@smallexample +10 PRINT *,'HOW MANY + 1 SPACES?' +@end smallexample + +@noindent +@command{g77}, and many other compilers, virtually extend +the continued line through column 72 with spaces that become part +of the character constant, but Digital Fortran normally didn't, +leaving only one space between @samp{MANY} and @samp{SPACES?} +in the output of the above statement. + +Fairly recently, at least one version of Digital Fortran +was enhanced to provide the other behavior when a +command-line option is specified, apparently due to demand +from readers of the USENET group @file{comp.lang.fortran} +to offer conformance to this widespread practice in the +industry. +@command{g77} should return the favor by offering conformance +to Digital's approach to handling the above example. + +@node Fortran Preprocessor +@subsection Fortran Preprocessor + +@command{g77} should offer a preprocessor designed specifically +for Fortran to replace @samp{cpp -traditional}. +There are several out there worth evaluating, at least. + +Such a preprocessor would recognize Hollerith constants, +properly parse comments and character constants, and so on. +It might also recognize, process, and thus preprocess +files included via the @code{INCLUDE} directive. + +@node Bit Operations on Floating-point Data +@subsection Bit Operations on Floating-point Data +@cindex @code{And} intrinsic +@cindex intrinsics, @code{And} +@cindex @code{Or} intrinsic +@cindex intrinsics, @code{Or} +@cindex @code{Shift} intrinsic +@cindex intrinsics, @code{Shift} + +@command{g77} does not allow @code{REAL} and other non-integral types for +arguments to intrinsics like @code{And}, @code{Or}, and @code{Shift}. + +For example, this program is rejected by @command{g77}, because +the intrinsic @code{Iand} does not accept @code{REAL} arguments: + +@smallexample +DATA A/7.54/, B/9.112/ +PRINT *, IAND(A, B) +END +@end smallexample + +@node Really Ugly Character Assignments +@subsection Really Ugly Character Assignments + +An option such as @option{-fugly-char} should be provided +to allow + +@smallexample +REAL*8 A1 +DATA A1 / '12345678' / +@end smallexample + +and: + +@smallexample +REAL*8 A1 +A1 = 'ABCDEFGH' +@end smallexample + +@node POSIX Standard +@subsection @code{POSIX} Standard + +@command{g77} should support the POSIX standard for Fortran. + +@node Floating-point Exception Handling +@subsection Floating-point Exception Handling +@cindex floating-point, exceptions +@cindex exceptions, floating-point +@cindex FPE handling +@cindex NaN values + +The @command{gcc} backend and, consequently, @command{g77}, currently provides no +general control over whether or not floating-point exceptions are trapped or +ignored. +(Ignoring them typically results in NaN values being +propagated in systems that conform to IEEE 754.) +The behavior is normally inherited from the system-dependent startup +code, though some targets, such as the Alpha, have code generation +options which change the behavior. + +Most systems provide some C-callable mechanism to change this; this can +be invoked at startup using @command{gcc}'s @code{constructor} attribute. +For example, just compiling and linking the following C code with your +program will turn on exception trapping for the ``common'' exceptions +on a GNU system using glibc 2.2 or newer: + +@smallexample +#define _GNU_SOURCE 1 +#include <fenv.h> +static void __attribute__ ((constructor)) +trapfpe () +@{ + /* Enable some exceptions. At startup all exceptions are masked. */ + + feenableexcept (FE_INVALID|FE_DIVBYZERO|FE_OVERFLOW); +@} +@end smallexample + +A convenient trick is to compile this something like: +@smallexample +gcc -o libtrapfpe.a trapfpe.c +@end smallexample +and then use it by adding @option{-trapfpe} to the @command{g77} command line +when linking. + +@node Nonportable Conversions +@subsection Nonportable Conversions +@cindex nonportable conversions +@cindex conversions, nonportable + +@command{g77} doesn't accept some particularly nonportable, +silent data-type conversions such as @code{LOGICAL} +to @code{REAL} (as in @samp{A=.FALSE.}, where @samp{A} +is type @code{REAL}), that other compilers might +quietly accept. + +Some of these conversions are accepted by @command{g77} +when the @option{-fugly-logint} option is specified. +Perhaps it should accept more or all of them. + +@node Large Automatic Arrays +@subsection Large Automatic Arrays +@cindex automatic arrays +@cindex arrays, automatic + +Currently, automatic arrays always are allocated on the stack. +For situations where the stack cannot be made large enough, +@command{g77} should offer a compiler option that specifies +allocation of automatic arrays in heap storage. + +@node Support for Threads +@subsection Support for Threads +@cindex threads +@cindex parallel processing + +Neither the code produced by @command{g77} nor the @code{libg2c} library +are thread-safe, nor does @command{g77} have support for parallel processing +(other than the instruction-level parallelism available on some +processors). +A package such as PVM might help here. + +@node Enabling Debug Lines +@subsection Enabling Debug Lines +@cindex debug line +@cindex comment line, debug + +An option such as @option{-fdebug-lines} should be provided +to turn fixed-form lines beginning with @samp{D} +to be treated as if they began with a space, +instead of as if they began with a @samp{C} +(as comment lines). + +@node Better Warnings +@subsection Better Warnings + +Because of how @command{g77} generates code via the back end, +it doesn't always provide warnings the user wants. +Consider: + +@smallexample +PROGRAM X +PRINT *, A +END +@end smallexample + +Currently, the above is not flagged as a case of +using an uninitialized variable, +because @command{g77} generates a run-time library call that looks, +to the GBE, like it might actually @emph{modify} @samp{A} at run time. +(And, in fact, depending on the previous run-time library call, +it would!) + +Fixing this requires one of the following: + +@itemize @bullet +@item +Switch to new library, @code{libg77}, that provides +a more ``clean'' interface, +vis-a-vis input, output, and modified arguments, +so the GBE can tell what's going on. + +This would provide a pretty big performance improvement, +at least theoretically, and, ultimately, in practice, +for some types of code. + +@item +Have @command{g77} pass a pointer to a temporary +containing a copy of @samp{A}, +instead of to @samp{A} itself. +The GBE would then complain about the copy operation +involving a potentially uninitialized variable. + +This might also provide a performance boost for some code, +because @samp{A} might then end up living in a register, +which could help with inner loops. + +@item +Have @command{g77} use a GBE construct similar to @code{ADDR_EXPR} +but with extra information on the fact that the +item pointed to won't be modified +(a la @code{const} in C). + +Probably the best solution for now, but not quite trivial +to implement in the general case. +@end itemize + +@node Gracefully Handle Sensible Bad Code +@subsection Gracefully Handle Sensible Bad Code + +@command{g77} generally should continue processing for +warnings and recoverable (user) errors whenever possible---that +is, it shouldn't gratuitously make bad or useless code. + +For example: + +@smallexample +INTRINSIC ZABS +CALL FOO(ZABS) +END +@end smallexample + +@noindent +When compiling the above with @option{-ff2c-intrinsics-disable}, +@command{g77} should indeed complain about passing @code{ZABS}, +but it still should compile, instead of rejecting +the entire @code{CALL} statement. +(Some of this is related to improving +the compiler internals to improve how statements are analyzed.) + +@node Non-standard Conversions +@subsection Non-standard Conversions + +@option{-Wconversion} and related should flag places where non-standard +conversions are found. +Perhaps much of this would be part of @option{-Wugly*}. + +@node Non-standard Intrinsics +@subsection Non-standard Intrinsics + +@command{g77} needs a new option, like @option{-Wintrinsics}, to warn about use of +non-standard intrinsics without explicit @code{INTRINSIC} statements for them. +This would help find code that might fail silently when ported to another +compiler. + +@node Modifying DO Variable +@subsection Modifying @code{DO} Variable + +@command{g77} should warn about modifying @code{DO} variables +via @code{EQUIVALENCE}. +(The internal information gathered to produce this warning +might also be useful in setting the +internal ``doiter'' flag for a variable or even array +reference within a loop, since that might produce faster code someday.) + +For example, this code is invalid, so @command{g77} should warn about +the invalid assignment to @samp{NOTHER}: + +@smallexample +EQUIVALENCE (I, NOTHER) +DO I = 1, 100 + IF (I.EQ. 10) NOTHER = 20 +END DO +@end smallexample + +@node Better Pedantic Compilation +@subsection Better Pedantic Compilation + +@command{g77} needs to support @option{-fpedantic} more thoroughly, +and use it only to generate +warnings instead of rejecting constructs outright. +Have it warn: +if a variable that dimensions an array is not a dummy or placed +explicitly in @code{COMMON} (F77 does not allow it to be +placed in @code{COMMON} via @code{EQUIVALENCE}); if specification statements +follow statement-function-definition statements; about all sorts of +syntactic extensions. + +@node Warn About Implicit Conversions +@subsection Warn About Implicit Conversions + +@command{g77} needs a @option{-Wpromotions} option to warn if source code appears +to expect automatic, silent, and +somewhat dangerous compiler-assisted conversion of @code{REAL(KIND=1)} +constants to @code{REAL(KIND=2)} based on context. + +For example, it would warn about cases like this: + +@smallexample +DOUBLE PRECISION FOO +PARAMETER (TZPHI = 9.435784839284958) +FOO = TZPHI * 3D0 +@end smallexample + +@node Invalid Use of Hollerith Constant +@subsection Invalid Use of Hollerith Constant + +@command{g77} should disallow statements like @samp{RETURN 2HAB}, +which are invalid in both source forms +(unlike @samp{RETURN (2HAB)}, +which probably still makes no sense but at least can +be reliably parsed). +Fixed-form processing rejects it, but not free-form, except +in a way that is a bit difficult to understand. + +@node Dummy Array Without Dimensioning Dummy +@subsection Dummy Array Without Dimensioning Dummy + +@command{g77} should complain when a list of dummy arguments containing an +adjustable dummy array does +not also contain every variable listed in the dimension list of the +adjustable array. + +Currently, @command{g77} does complain about a variable that +dimensions an array but doesn't appear in any dummy list or @code{COMMON} +area, but this needs to be extended to catch cases where it doesn't appear in +every dummy list that also lists any arrays it dimensions. + +For example, @command{g77} should warn about the entry point @samp{ALT} +below, since it includes @samp{ARRAY} but not @samp{ISIZE} in its +list of arguments: + +@smallexample +SUBROUTINE PRIMARY(ARRAY, ISIZE) +REAL ARRAY(ISIZE) +ENTRY ALT(ARRAY) +@end smallexample + +@node Invalid FORMAT Specifiers +@subsection Invalid FORMAT Specifiers + +@command{g77} should check @code{FORMAT} specifiers for validity +as it does @code{FORMAT} statements. + +For example, a diagnostic would be produced for: + +@smallexample +PRINT 'HI THERE!' !User meant PRINT *, 'HI THERE!' +@end smallexample + +@node Ambiguous Dialects +@subsection Ambiguous Dialects + +@command{g77} needs a set of options such as @option{-Wugly*}, @option{-Wautomatic}, +@option{-Wvxt}, @option{-Wf90}, and so on. +These would warn about places in the user's source where ambiguities +are found, helpful in resolving ambiguities in the program's +dialect or dialects. + +@node Unused Labels +@subsection Unused Labels + +@command{g77} should warn about unused labels when @option{-Wunused} is in effect. + +@node Informational Messages +@subsection Informational Messages + +@command{g77} needs an option to suppress information messages (notes). +@option{-w} does this but also suppresses warnings. +The default should be to suppress info messages. + +Perhaps info messages should simply be eliminated. + +@node Uninitialized Variables at Run Time +@subsection Uninitialized Variables at Run Time + +@command{g77} needs an option to initialize everything (not otherwise +explicitly initialized) to ``weird'' +(machine-dependent) values, e.g. NaNs, bad (non-@code{NULL}) pointers, and +largest-magnitude integers, would help track down references to +some kinds of uninitialized variables at run time. + +Note that use of the options @samp{-O -Wuninitialized} can catch +many such bugs at compile time. + +@node Portable Unformatted Files +@subsection Portable Unformatted Files + +@cindex unformatted files +@cindex file formats +@cindex binary data +@cindex byte ordering +@command{g77} has no facility for exchanging unformatted files with systems +using different number formats---even differing only in endianness (byte +order)---or written by other compilers. Some compilers provide +facilities at least for doing byte-swapping during unformatted I/O. + +It is unrealistic to expect to cope with exchanging unformatted files +with arbitrary other compiler runtimes, but the @command{g77} runtime +should at least be able to read files written by @command{g77} on systems +with different number formats, particularly if they differ only in byte +order. + +In case you do need to write a program to translate to or from +@command{g77} (@code{libf2c}) unformatted files, they are written as +follows: +@table @asis +@item Sequential +Unformatted sequential records consist of +@enumerate +@item +A number giving the length of the record contents; +@item +the length of record contents again (for backspace). +@end enumerate + +The record length is of C type +@code{long}; this means that it is 8 bytes on 64-bit systems such as +Alpha GNU/Linux and 4 bytes on other systems, such as x86 GNU/Linux. +Consequently such files cannot be exchanged between 64-bit and 32-bit +systems, even with the same basic number format. +@item Direct access +Unformatted direct access files form a byte stream of length +@var{records}*@var{recl} bytes, where @var{records} is the maximum +record number (@code{REC=@var{records}}) written and @var{recl} is the +record length in bytes specified in the @code{OPEN} statement +(@code{RECL=@var{recl}}). Data appear in the records as determined by +the relevant @code{WRITE} statement. Dummy records with arbitrary +contents appear in the file in place of records which haven't been +written. +@end table + +Thus for exchanging a sequential or direct access unformatted file +between big- and little-endian 32-bit systems using IEEE 754 floating +point it would be sufficient to reverse the bytes in consecutive words +in the file if, and @emph{only} if, only @code{REAL*4}, @code{COMPLEX}, +@code{INTEGER*4} and/or @code{LOGICAL*4} data have been written to it by +@command{g77}. + +If necessary, it is possible to do byte-oriented i/o with @command{g77}'s +@code{FGETC} and @code{FPUTC} intrinsics. Byte-swapping can be done in +Fortran by equivalencing larger sized variables to an @code{INTEGER*1} +array or a set of scalars. + +@cindex HDF +@cindex PDB +If you need to exchange binary data between arbitrary system and +compiler variations, we recommend using a portable binary format with +Fortran bindings, such as NCSA's HDF (@uref{http://hdf.ncsa.uiuc.edu/}) +or PACT's PDB@footnote{No, not @emph{that} one.} +(@uref{http://www.llnl.gov/def_sci/pact/pact_homepage.html}). (Unlike, +say, CDF or XDR, HDF-like systems write in the native number formats and +only incur overhead when they are read on a system with a different +format.) A future @command{g77} runtime library should use such +techniques. + +@node Better List-directed I/O +@subsection Better List-directed I/O + +Values output using list-directed I/O +(@samp{PRINT *, R, D}) +should be written with a field width, precision, and so on +appropriate for the type (precision) of each value. + +(Currently, no distinction is made between single-precision +and double-precision values +by @code{libf2c}.) + +It is likely this item will require the @code{libg77} project +to be undertaken. + +In the meantime, use of formatted I/O is recommended. +While it might be of little consolation, +@command{g77} does support @samp{FORMAT(F<WIDTH>.4)}, for example, +as long as @samp{WIDTH} is defined as a named constant +(via @code{PARAMETER}). +That at least allows some compile-time specification +of the precision of a data type, +perhaps controlled by preprocessing directives. + +@node Default to Console I/O +@subsection Default to Console I/O + +The default I/O units, +specified by @samp{READ @var{fmt}}, +@samp{READ (UNIT=*)}, +@samp{WRITE (UNIT=*)}, and +@samp{PRINT @var{fmt}}, +should not be units 5 (input) and 6 (output), +but, rather, unit numbers not normally available +for use in statements such as @code{OPEN} and @code{CLOSE}. + +Changing this would allow a program to connect units 5 and 6 +to files via @code{OPEN}, +but still use @samp{READ (UNIT=*)} and @samp{PRINT} +to do I/O to the ``console''. + +This change probably requires the @code{libg77} project. + +@node Labels Visible to Debugger +@subsection Labels Visible to Debugger + +@command{g77} should output debugging information for statements labels, +for use by debuggers that know how to support them. +Same with weirder things like construct names. +It is not yet known if any debug formats or debuggers support these. + +@node Disappointments +@section Disappointments and Misunderstandings + +These problems are perhaps regrettable, but we don't know any practical +way around them for now. + +@menu +* Mangling of Names:: @samp{SUBROUTINE FOO} is given + external name @samp{foo_}. +* Multiple Definitions of External Names:: No doing both @samp{COMMON /FOO/} + and @samp{SUBROUTINE FOO}. +* Limitation on Implicit Declarations:: No @samp{IMPLICIT CHARACTER*(*)}. +@end menu + +@node Mangling of Names +@subsection Mangling of Names in Source Code +@cindex naming issues +@cindex external names +@cindex common blocks +@cindex name space +@cindex underscore + +The current external-interface design, which includes naming of +external procedures, COMMON blocks, and the library interface, +has various usability problems, including things like adding +underscores where not really necessary (and preventing easier +inter-language operability) and yet not providing complete +namespace freedom for user C code linked with Fortran apps (due +to the naming of functions in the library, among other things). + +Project GNU should at least get all this ``right'' for systems +it fully controls, such as the Hurd, and provide defaults and +options for compatibility with existing systems and interoperability +with popular existing compilers. + +@node Multiple Definitions of External Names +@subsection Multiple Definitions of External Names +@cindex block data +@cindex BLOCK DATA statement +@cindex statements, BLOCK DATA +@cindex @code{COMMON} statement +@cindex statements, @code{COMMON} +@cindex naming conflicts + +@command{g77} doesn't allow a common block and an external procedure or +@code{BLOCK DATA} to have the same name. +Some systems allow this, but @command{g77} does not, +to be compatible with @command{f2c}. + +@command{g77} could special-case the way it handles +@code{BLOCK DATA}, since it is not compatible with @command{f2c} in this +particular area (necessarily, since @command{g77} offers an +important feature here), but +it is likely that such special-casing would be very annoying to people +with programs that use @samp{EXTERNAL FOO}, with no other mention of +@samp{FOO} in the same program unit, to refer to external procedures, since +the result would be that @command{g77} would treat these references as requests to +force-load BLOCK DATA program units. + +In that case, if @command{g77} modified +names of @code{BLOCK DATA} so they could have the same names as +@code{COMMON}, users +would find that their programs wouldn't link because the @samp{FOO} procedure +didn't have its name translated the same way. + +(Strictly speaking, +@command{g77} could emit a null-but-externally-satisfying definition of +@samp{FOO} with its name transformed as if it had been a +@code{BLOCK DATA}, but that probably invites more trouble than it's +worth.) + +@node Limitation on Implicit Declarations +@subsection Limitation on Implicit Declarations +@cindex IMPLICIT CHARACTER*(*) statement +@cindex statements, IMPLICIT CHARACTER*(*) + +@command{g77} disallows @code{IMPLICIT CHARACTER*(*)}. +This is not standard-conforming. + +@node Non-bugs +@section Certain Changes We Don't Want to Make + +This section lists changes that people frequently request, but which +we do not make because we think GNU Fortran is better without them. + +@menu +* Backslash in Constants:: Why @samp{'\\'} is a constant that + is one, not two, characters long. +* Initializing Before Specifying:: Why @samp{DATA VAR/1/} can't precede + @samp{COMMON VAR}. +* Context-Sensitive Intrinsicness:: Why @samp{CALL SQRT} won't work. +* Context-Sensitive Constants:: Why @samp{9.435784839284958} is a + single-precision constant, + and might be interpreted as + @samp{9.435785} or similar. +* Equivalence Versus Equality:: Why @samp{.TRUE. .EQ. .TRUE.} won't work. +* Order of Side Effects:: Why @samp{J = IFUNC() - IFUNC()} might + not behave as expected. +@end menu + +@node Backslash in Constants +@subsection Backslash in Constants +@cindex backslash +@cindex @command{f77} support +@cindex support, @command{f77} + +In the opinion of many experienced Fortran users, +@option{-fno-backslash} should be the default, not @option{-fbackslash}, +as currently set by @command{g77}. + +First of all, you can always specify +@option{-fno-backslash} to turn off this processing. + +Despite not being within the spirit (though apparently within the +letter) of the ANSI FORTRAN 77 standard, @command{g77} defaults to +@option{-fbackslash} because that is what most UNIX @command{f77} commands +default to, and apparently lots of code depends on this feature. + +This is a particularly troubling issue. +The use of a C construct in the midst of Fortran code +is bad enough, worse when it makes existing Fortran +programs stop working (as happens when programs written +for non-UNIX systems are ported to UNIX systems with +compilers that provide the @option{-fbackslash} feature +as the default---sometimes with no option to turn it off). + +The author of GNU Fortran wished, for reasons of linguistic +purity, to make @option{-fno-backslash} the default for GNU +Fortran and thus require users of UNIX @command{f77} and @command{f2c} +to specify @option{-fbackslash} to get the UNIX behavior. + +However, the realization that @command{g77} is intended as +a replacement for @emph{UNIX} @command{f77}, caused the author +to choose to make @command{g77} as compatible with +@command{f77} as feasible, which meant making @option{-fbackslash} +the default. + +The primary focus on compatibility is at the source-code +level, and the question became ``What will users expect +a replacement for @command{f77} to do, by default?'' +Although at least one UNIX @command{f77} does not provide +@option{-fbackslash} as a default, it appears that +the majority of them do, which suggests that +the majority of code that is compiled by UNIX @command{f77} +compilers expects @option{-fbackslash} to be the default. + +It is probably the case that more code exists +that would @emph{not} work with @option{-fbackslash} +in force than code that requires it be in force. + +However, most of @emph{that} code is not being compiled +with @command{f77}, +and when it is, new build procedures (shell scripts, +makefiles, and so on) must be set up anyway so that +they work under UNIX. +That makes a much more natural and safe opportunity for +non-UNIX users to adapt their build procedures for +@command{g77}'s default of @option{-fbackslash} than would +exist for the majority of UNIX @command{f77} users who +would have to modify existing, working build procedures +to explicitly specify @option{-fbackslash} if that was +not the default. + +One suggestion has been to configure the default for +@option{-fbackslash} (and perhaps other options as well) +based on the configuration of @command{g77}. + +This is technically quite straightforward, but will be avoided +even in cases where not configuring defaults to be +dependent on a particular configuration greatly inconveniences +some users of legacy code. + +Many users appreciate the GNU compilers because they provide an +environment that is uniform across machines. +These users would be +inconvenienced if the compiler treated things like the +format of the source code differently on certain machines. + +Occasionally users write programs intended only for a particular machine +type. +On these occasions, the users would benefit if the GNU Fortran compiler +were to support by default the same dialect as the other compilers on +that machine. +But such applications are rare. +And users writing a +program to run on more than one type of machine cannot possibly benefit +from this kind of compatibility. +(This is consistent with the design goals for @command{gcc}. +To change them for @command{g77}, you must first change them +for @command{gcc}. +Do not ask the maintainers of @command{g77} to do this for you, +or to disassociate @command{g77} from the widely understood, if +not widely agreed-upon, goals for GNU compilers in general.) + +This is why GNU Fortran does and will treat backslashes in the same +fashion on all types of machines (by default). +@xref{Direction of Language Development}, for more information on +this overall philosophy guiding the development of the GNU Fortran +language. + +Of course, users strongly concerned about portability should indicate +explicitly in their build procedures which options are expected +by their source code, or write source code that has as few such +expectations as possible. + +For example, avoid writing code that depends on backslash (@samp{\}) +being interpreted either way in particular, such as by +starting a program unit with: + +@smallexample +CHARACTER BACKSL +PARAMETER (BACKSL = '\\') +@end smallexample + +@noindent +Then, use concatenation of @samp{BACKSL} anyplace a backslash +is desired. +In this way, users can write programs which have the same meaning +in many Fortran dialects. + +(However, this technique does not work for Hollerith constants---which +is just as well, since the only generally portable uses for Hollerith +constants are in places where character constants can and should +be used instead, for readability.) + +@node Initializing Before Specifying +@subsection Initializing Before Specifying +@cindex initialization, statement placement +@cindex placing initialization statements + +@command{g77} does not allow @samp{DATA VAR/1/} to appear in the +source code before @samp{COMMON VAR}, +@samp{DIMENSION VAR(10)}, @samp{INTEGER VAR}, and so on. +In general, @command{g77} requires initialization of a variable +or array to be specified @emph{after} all other specifications +of attributes (type, size, placement, and so on) of that variable +or array are specified (though @emph{confirmation} of data type is +permitted). + +It is @emph{possible} @command{g77} will someday allow all of this, +even though it is not allowed by the FORTRAN 77 standard. + +Then again, maybe it is better to have +@command{g77} always require placement of @code{DATA} +so that it can possibly immediately write constants +to the output file, thus saving time and space. + +That is, @samp{DATA A/1000000*1/} should perhaps always +be immediately writable to canonical assembler, unless it's already known +to be in a @code{COMMON} area following as-yet-uninitialized stuff, +and to do this it cannot be followed by @samp{COMMON A}. + +@node Context-Sensitive Intrinsicness +@subsection Context-Sensitive Intrinsicness +@cindex intrinsics, context-sensitive +@cindex context-sensitive intrinsics + +@command{g77} treats procedure references to @emph{possible} intrinsic +names as always enabling their intrinsic nature, regardless of +whether the @emph{form} of the reference is valid for that +intrinsic. + +For example, @samp{CALL SQRT} is interpreted by @command{g77} as +an invalid reference to the @code{SQRT} intrinsic function, +because the reference is a subroutine invocation. + +First, @command{g77} recognizes the statement @samp{CALL SQRT} +as a reference to a @emph{procedure} named @samp{SQRT}, not +to a @emph{variable} with that name (as it would for a statement +such as @samp{V = SQRT}). + +Next, @command{g77} establishes that, in the program unit being compiled, +@code{SQRT} is an intrinsic---not a subroutine that +happens to have the same name as an intrinsic (as would be +the case if, for example, @samp{EXTERNAL SQRT} was present). + +Finally, @command{g77} recognizes that the @emph{form} of the +reference is invalid for that particular intrinsic. +That is, it recognizes that it is invalid for an intrinsic +@emph{function}, such as @code{SQRT}, to be invoked as +a @emph{subroutine}. + +At that point, @command{g77} issues a diagnostic. + +Some users claim that it is ``obvious'' that @samp{CALL SQRT} +references an external subroutine of their own, not an +intrinsic function. + +However, @command{g77} knows about intrinsic +subroutines, not just functions, and is able to support both having +the same names, for example. + +As a result of this, @command{g77} rejects calls +to intrinsics that are not subroutines, and function invocations +of intrinsics that are not functions, just as it (and most compilers) +rejects invocations of intrinsics with the wrong number (or types) +of arguments. + +So, use the @samp{EXTERNAL SQRT} statement in a program unit that calls +a user-written subroutine named @samp{SQRT}. + +@node Context-Sensitive Constants +@subsection Context-Sensitive Constants +@cindex constants, context-sensitive +@cindex context-sensitive constants + +@command{g77} does not use context to determine the types of +constants or named constants (@code{PARAMETER}), except +for (non-standard) typeless constants such as @samp{'123'O}. + +For example, consider the following statement: + +@smallexample +PRINT *, 9.435784839284958 * 2D0 +@end smallexample + +@noindent +@command{g77} will interpret the (truncated) constant +@samp{9.435784839284958} as a @code{REAL(KIND=1)}, not @code{REAL(KIND=2)}, +constant, because the suffix @code{D0} is not specified. + +As a result, the output of the above statement when +compiled by @command{g77} will appear to have ``less precision'' +than when compiled by other compilers. + +In these and other cases, some compilers detect the +fact that a single-precision constant is used in +a double-precision context and therefore interpret the +single-precision constant as if it was @emph{explicitly} +specified as a double-precision constant. +(This has the effect of appending @emph{decimal}, not +@emph{binary}, zeros to the fractional part of the +number---producing different computational results.) + +The reason this misfeature is dangerous is that a slight, +apparently innocuous change to the source code can change +the computational results. +Consider: + +@smallexample +REAL ALMOST, CLOSE +DOUBLE PRECISION FIVE +PARAMETER (ALMOST = 5.000000000001) +FIVE = 5 +CLOSE = 5.000000000001 +PRINT *, 5.000000000001 - FIVE +PRINT *, ALMOST - FIVE +PRINT *, CLOSE - FIVE +END +@end smallexample + +@noindent +Running the above program should +result in the same value being +printed three times. +With @command{g77} as the compiler, +it does. + +However, compiled by many other compilers, +running the above program would print +two or three distinct values, because +in two or three of the statements, the +constant @samp{5.000000000001}, which +on most systems is exactly equal to @samp{5.} +when interpreted as a single-precision constant, +is instead interpreted as a double-precision +constant, preserving the represented +precision. +However, this ``clever'' promotion of +type does not extend to variables or, +in some compilers, to named constants. + +Since programmers often are encouraged to replace manifest +constants or permanently-assigned variables with named +constants (@code{PARAMETER} in Fortran), and might need +to replace some constants with variables having the same +values for pertinent portions of code, +it is important that compilers treat code so modified in the +same way so that the results of such programs are the same. +@command{g77} helps in this regard by treating constants just +the same as variables in terms of determining their types +in a context-independent way. + +Still, there is a lot of existing Fortran code that has +been written to depend on the way other compilers freely +interpret constants' types based on context, so anything +@command{g77} can do to help flag cases of this in such code +could be very helpful. + +@node Equivalence Versus Equality +@subsection Equivalence Versus Equality +@cindex .EQV., with integer operands +@cindex comparing logical expressions +@cindex logical expressions, comparing + +Use of @code{.EQ.} and @code{.NE.} on @code{LOGICAL} operands +is not supported, except via @option{-fugly-logint}, which is not +recommended except for legacy code (where the behavior expected +by the @emph{code} is assumed). + +Legacy code should be changed, as resources permit, to use @code{.EQV.} +and @code{.NEQV.} instead, as these are permitted by the various +Fortran standards. + +New code should never be written expecting @code{.EQ.} or @code{.NE.} +to work if either of its operands is @code{LOGICAL}. + +The problem with supporting this ``feature'' is that there is +unlikely to be consensus on how it works, as illustrated by the +following sample program: + +@smallexample +LOGICAL L,M,N +DATA L,M,N /3*.FALSE./ +IF (L.AND.M.EQ.N) PRINT *,'L.AND.M.EQ.N' +END +@end smallexample + +The issue raised by the above sample program is: what is the +precedence of @code{.EQ.} (and @code{.NE.}) when applied to +@code{LOGICAL} operands? + +Some programmers will argue that it is the same as the precedence +for @code{.EQ.} when applied to numeric (such as @code{INTEGER}) +operands. +By this interpretation, the subexpression @samp{M.EQ.N} must be +evaluated first in the above program, resulting in a program that, +when run, does not execute the @code{PRINT} statement. + +Other programmers will argue that the precedence is the same as +the precedence for @code{.EQV.}, which is restricted by the standards +to @code{LOGICAL} operands. +By this interpretation, the subexpression @samp{L.AND.M} must be +evaluated first, resulting in a program that @emph{does} execute +the @code{PRINT} statement. + +Assigning arbitrary semantic interpretations to syntactic expressions +that might legitimately have more than one ``obvious'' interpretation +is generally unwise. + +The creators of the various Fortran standards have done a good job +in this case, requiring a distinct set of operators (which have their +own distinct precedence) to compare @code{LOGICAL} operands. +This requirement results in expression syntax with more certain +precedence (without requiring substantial context), making it easier +for programmers to read existing code. +@command{g77} will avoid muddying up elements of the Fortran language +that were well-designed in the first place. + +(Ask C programmers about the precedence of expressions such as +@samp{(a) & (b)} and @samp{(a) - (b)}---they cannot even tell +you, without knowing more context, whether the @samp{&} and @samp{-} +operators are infix (binary) or unary!) + +Most dangerous of all is the fact that, +even assuming consensus on its meaning, +an expression like @samp{L.AND.M.EQ.N}, +if it is the result of a typographical error, +doesn't @emph{look} like it has such a typo. +Even experienced Fortran programmers would not likely notice that +@samp{L.AND.M.EQV.N} was, in fact, intended. + +So, this is a prime example of a circumstance in which +a quality compiler diagnoses the code, +instead of leaving it up to someone debugging it +to know to turn on special compiler options +that might diagnose it. + +@node Order of Side Effects +@subsection Order of Side Effects +@cindex side effects, order of evaluation +@cindex order of evaluation, side effects + +@command{g77} does not necessarily produce code that, when run, performs +side effects (such as those performed by function invocations) +in the same order as in some other compiler---or even in the same +order as another version, port, or invocation (using different +command-line options) of @command{g77}. + +It is never safe to depend on the order of evaluation of side effects. +For example, an expression like this may very well behave differently +from one compiler to another: + +@smallexample +J = IFUNC() - IFUNC() +@end smallexample + +@noindent +There is no guarantee that @samp{IFUNC} will be evaluated in any particular +order. +Either invocation might happen first. +If @samp{IFUNC} returns 5 the first time it is invoked, and +returns 12 the second time, @samp{J} might end up with the +value @samp{7}, or it might end up with @samp{-7}. + +Generally, in Fortran, procedures with side-effects intended to +be visible to the caller are best designed as @emph{subroutines}, +not functions. +Examples of such side-effects include: + +@itemize @bullet +@item +The generation of random numbers +that are intended to influence return values. + +@item +Performing I/O +(other than internal I/O to local variables). + +@item +Updating information in common blocks. +@end itemize + +An example of a side-effect that is not intended to be visible +to the caller is a function that maintains a cache of recently +calculated results, intended solely to speed repeated invocations +of the function with identical arguments. +Such a function can be safely used in expressions, because +if the compiler optimizes away one or more calls to the +function, operation of the program is unaffected (aside +from being speeded up). + +@node Warnings and Errors +@section Warning Messages and Error Messages + +@cindex error messages +@cindex warnings vs errors +@cindex messages, warning and error +The GNU compiler can produce two kinds of diagnostics: errors and +warnings. +Each kind has a different purpose: + +@itemize @w{} +@item +@emph{Errors} report problems that make it impossible to compile your +program. +GNU Fortran reports errors with the source file name, line +number, and column within the line where the problem is apparent. + +@item +@emph{Warnings} report other unusual conditions in your code that +@emph{might} indicate a problem, although compilation can (and does) +proceed. +Warning messages also report the source file name, line number, +and column information, +but include the text @samp{warning:} to distinguish them +from error messages. +@end itemize + +Warnings might indicate danger points where you should check to make sure +that your program really does what you intend; or the use of obsolete +features; or the use of nonstandard features of GNU Fortran. +Many warnings are issued only if you ask for them, with one of the +@option{-W} options (for instance, @option{-Wall} requests a variety of +useful warnings). + +@emph{Note:} Currently, the text of the line and a pointer to the column +is printed in most @command{g77} diagnostics. + +@xref{Warning Options,,Options to Request or Suppress Warnings}, for +more detail on these and related command-line options. + +@node Open Questions +@chapter Open Questions + +Please consider offering useful answers to these questions! + +@itemize @bullet +@item +@code{LOC()} and other intrinsics are probably somewhat misclassified. +Is the a need for more precise classification of intrinsics, and if so, +what are the appropriate groupings? +Is there a need to individually +enable/disable/delete/hide intrinsics from the command line? +@end itemize + +@node Bugs +@chapter Reporting Bugs +@cindex bugs +@cindex reporting bugs + +Your bug reports play an essential role in making GNU Fortran reliable. + +When you encounter a problem, the first thing to do is to see if it is +already known. @xref{Trouble}. If it isn't known, then you should +report the problem. + +@menu +* Criteria: Bug Criteria. Have you really found a bug? +* Reporting: Bug Reporting. How to report a bug effectively. +@end menu + +@xref{Trouble,,Known Causes of Trouble with GNU Fortran}, +for information on problems we already know about. + +@xref{Service,,How To Get Help with GNU Fortran}, +for information on where to ask for help. + +@node Bug Criteria +@section Have You Found a Bug? +@cindex bug criteria + +If you are not sure whether you have found a bug, here are some guidelines: + +@itemize @bullet +@cindex fatal signal +@cindex core dump +@item +If the compiler gets a fatal signal, for any input whatever, that is a +compiler bug. +Reliable compilers never crash---they just remain obsolete. + +@cindex invalid assembly code +@cindex assembly code, invalid +@item +If the compiler produces invalid assembly code, for any input whatever, +@c (except an @code{asm} statement), +that is a compiler bug, unless the +compiler reports errors (not just warnings) which would ordinarily +prevent the assembler from being run. + +@cindex undefined behavior +@cindex undefined function value +@item +If the compiler produces valid assembly code that does not correctly +execute the input source code, that is a compiler bug. + +However, you must double-check to make sure, because you might have run +into an incompatibility between GNU Fortran and traditional Fortran. +@c (@pxref{Incompatibilities}). +These incompatibilities might be considered +bugs, but they are inescapable consequences of valuable features. + +Or you might have a program whose behavior is undefined, which happened +by chance to give the desired results with another Fortran compiler. +It is best to check the relevant Fortran standard thoroughly if +it is possible that the program indeed does something undefined. + +After you have localized the error to a single source line, it should +be easy to check for these things. +If your program is correct and well defined, you have found +a compiler bug. + +It might help if, in your submission, you identified the specific +language in the relevant Fortran standard that specifies the +desired behavior, if it isn't likely to be obvious and agreed-upon +by all Fortran users. + +@item +If the compiler produces an error message for valid input, that is a +compiler bug. + +@cindex invalid input +@item +If the compiler does not produce an error message for invalid input, +that is a compiler bug. +However, you should note that your idea of +``invalid input'' might be someone else's idea +of ``an extension'' or ``support for traditional practice''. + +@item +If you are an experienced user of Fortran compilers, your suggestions +for improvement of GNU Fortran are welcome in any case. +@end itemize + +Many, perhaps most, bug reports against @command{g77} turn out to +be bugs in the user's code. +While we find such bug reports educational, they sometimes take +a considerable amount of time to track down or at least respond +to---time we could be spending making @command{g77}, not some user's +code, better. + +Some steps you can take to verify that the bug is not certainly +in the code you're compiling with @command{g77}: + +@itemize @bullet +@item +Compile your code using the @command{g77} options @samp{-W -Wall -O}. +These options enable many useful warning; the @option{-O} option +enables flow analysis that enables the uninitialized-variable +warning. + +If you investigate the warnings and find evidence of possible bugs +in your code, fix them first and retry @command{g77}. + +@item +Compile your code using the @command{g77} options @option{-finit-local-zero}, +@option{-fno-automatic}, @option{-ffloat-store}, and various +combinations thereof. + +If your code works with any of these combinations, that is not +proof that the bug isn't in @command{g77}---a @command{g77} bug exposed +by your code might simply be avoided, or have a different, more subtle +effect, when different options are used---but it can be a +strong indicator that your code is making unwarranted assumptions +about the Fortran dialect and/or underlying machine it is +being compiled and run on. + +@xref{Overly Convenient Options,,Overly Convenient Command-Line Options}, +for information on the @option{-fno-automatic} and +@option{-finit-local-zero} options and how to convert +their use into selective changes in your own code. + +@item +@pindex ftnchek +Validate your code with @command{ftnchek} or a similar code-checking +tool. +@command{ftnchek} can be found at @uref{ftp://ftp.netlib.org/fortran} +or @uref{ftp://ftp.dsm.fordham.edu}. + +@pindex make +@cindex Makefile example +Here are some sample @file{Makefile} rules using @command{ftnchek} +``project'' files to do cross-file checking and @command{sfmakedepend} +(from @uref{ftp://ahab.rutgers.edu/pub/perl/sfmakedepend}) +to maintain dependencies automatically. +These assume the use of GNU @command{make}. + +@smallexample +# Dummy suffix for ftnchek targets: +.SUFFIXES: .chek +.PHONY: chekall + +# How to compile .f files (for implicit rule): +FC = g77 +# Assume `include' directory: +FFLAGS = -Iinclude -g -O -Wall + +# Flags for ftnchek: +CHEK1 = -array=0 -include=includes -noarray +CHEK2 = -nonovice -usage=1 -notruncation +CHEKFLAGS = $(CHEK1) $(CHEK2) + +# Run ftnchek with all the .prj files except the one corresponding +# to the target's root: +%.chek : %.f ; \ + ftnchek $(filter-out $*.prj,$(PRJS)) $(CHEKFLAGS) \ + -noextern -library $< + +# Derive a project file from a source file: +%.prj : %.f ; \ + ftnchek $(CHEKFLAGS) -noextern -project -library $< + +# The list of objects is assumed to be in variable OBJS. +# Sources corresponding to the objects: +SRCS = $(OBJS:%.o=%.f) +# ftnchek project files: +PRJS = $(OBJS:%.o=%.prj) + +# Build the program +prog: $(OBJS) ; \ + $(FC) -o $@ $(OBJS) + +chekall: $(PRJS) ; \ + ftnchek $(CHEKFLAGS) $(PRJS) + +prjs: $(PRJS) + +# For Emacs M-x find-tag: +TAGS: $(SRCS) ; \ + etags $(SRCS) + +# Rebuild dependencies: +depend: ; \ + sfmakedepend -I $(PLTLIBDIR) -I includes -a prj $(SRCS1) +@end smallexample + +@item +Try your code out using other Fortran compilers, such as @command{f2c}. +If it does not work on at least one other compiler (assuming the +compiler supports the features the code needs), that is a strong +indicator of a bug in the code. + +However, even if your code works on many compilers @emph{except} +@command{g77}, that does @emph{not} mean the bug is in @command{g77}. +It might mean the bug is in your code, and that @command{g77} simply +exposes it more readily than other compilers. +@end itemize + +@node Bug Reporting +@section How to Report Bugs +@cindex compiler bugs, reporting + +Bugs should be reported to our bug database. Please refer to +@uref{http://gcc.gnu.org/bugs.html} for up-to-date instructions how to +submit bug reports. Copies of this file in HTML (@file{bugs.html}) and +plain text (@file{BUGS}) are also part of GCC releases. + + +@node Service +@chapter How To Get Help with GNU Fortran + +If you need help installing, using or changing GNU Fortran, there are two +ways to find it: + +@itemize @bullet +@item +Look in the service directory for someone who might help you for a fee. +The service directory is found in the file named @file{SERVICE} in the +GCC distribution. + +@item +Send a message to @email{@value{email-help}}. +@end itemize + +@end ifset +@ifset INTERNALS +@node Adding Options +@chapter Adding Options +@cindex options, adding +@cindex adding options + +To add a new command-line option to @command{g77}, first decide +what kind of option you wish to add. +Search the @command{g77} and @command{gcc} documentation for one +or more options that is most closely like the one you want to add +(in terms of what kind of effect it has, and so on) to +help clarify its nature. + +@itemize @bullet +@item +@emph{Fortran options} are options that apply only +when compiling Fortran programs. +They are accepted by @command{g77} and @command{gcc}, but +they apply only when compiling Fortran programs. + +@item +@emph{Compiler options} are options that apply +when compiling most any kind of program. +@end itemize + +@emph{Fortran options} are listed in the file +@file{@value{path-g77}/lang-options.h}, +which is used during the build of @command{gcc} to +build a list of all options that are accepted by +at least one language's compiler. +This list goes into the @code{documented_lang_options} array +in @file{gcc/toplev.c}, which uses this array to +determine whether a particular option should be +offered to the linked-in front end for processing +by calling @code{lang_option_decode}, which, for +@command{g77}, is in @file{@value{path-g77}/com.c} and just +calls @code{ffe_decode_option}. + +If the linked-in front end ``rejects'' a +particular option passed to it, @file{toplev.c} +just ignores the option, because @emph{some} +language's compiler is willing to accept it. + +This allows commands like @samp{gcc -fno-asm foo.c bar.f} +to work, even though Fortran compilation does +not currently support the @option{-fno-asm} option; +even though the @code{f771} version of @code{lang_decode_option} +rejects @option{-fno-asm}, @file{toplev.c} doesn't +produce a diagnostic because some other language (C) +does accept it. + +This also means that commands like +@samp{g77 -fno-asm foo.f} yield no diagnostics, +despite the fact that no phase of the command was +able to recognize and process @option{-fno-asm}---perhaps +a warning about this would be helpful if it were +possible. + +Code that processes Fortran options is found in +@file{@value{path-g77}/top.c}, function @code{ffe_decode_option}. +This code needs to check positive and negative forms +of each option. + +The defaults for Fortran options are set in their +global definitions, also found in @file{@value{path-g77}/top.c}. +Many of these defaults are actually macros defined +in @file{@value{path-g77}/target.h}, since they might be +machine-specific. +However, since, in practice, GNU compilers +should behave the same way on all configurations +(especially when it comes to language constructs), +the practice of setting defaults in @file{target.h} +is likely to be deprecated and, ultimately, stopped +in future versions of @command{g77}. + +Accessor macros for Fortran options, used by code +in the @command{g77} FFE, are defined in @file{@value{path-g77}/top.h}. + +@emph{Compiler options} are listed in @file{gcc/toplev.c} +in the array @code{f_options}. +An option not listed in @code{lang_options} is +looked up in @code{f_options} and handled from there. + +The defaults for compiler options are set in the +global definitions for the corresponding variables, +some of which are in @file{gcc/toplev.c}. + +You can set different defaults for @emph{Fortran-oriented} +or @emph{Fortran-reticent} compiler options by changing +the source code of @command{g77} and rebuilding. +How to do this depends on the version of @command{g77}: + +@table @code +@item G77 0.5.24 (EGCS 1.1) +@itemx G77 0.5.25 (EGCS 1.2 - which became GCC 2.95) +Change the @code{lang_init_options} routine in @file{gcc/gcc/f/com.c}. + +(Note that these versions of @command{g77} +perform internal consistency checking automatically +when the @option{-fversion} option is specified.) + +@item G77 0.5.23 +@itemx G77 0.5.24 (EGCS 1.0) +Change the way @code{f771} handles the @option{-fset-g77-defaults} +option, which is always provided as the first option when +called by @command{g77} or @command{gcc}. + +This code is in @code{ffe_decode_options} in @file{@value{path-g77}/top.c}. +Have it change just the variables that you want to default +to a different setting for Fortran compiles compared to +compiles of other languages. + +The @option{-fset-g77-defaults} option is passed to @code{f771} +automatically because of the specification information +kept in @file{@value{path-g77}/lang-specs.h}. +This file tells the @command{gcc} command how to recognize, +in this case, Fortran source files (those to be preprocessed, +and those that are not), and further, how to invoke the +appropriate programs (including @code{f771}) to process +those source files. + +It is in @file{@value{path-g77}/lang-specs.h} that @option{-fset-g77-defaults}, +@option{-fversion}, and other options are passed, as appropriate, +even when the user has not explicitly specified them. +Other ``internal'' options such as @option{-quiet} also +are passed via this mechanism. +@end table + +@node Projects +@chapter Projects +@cindex projects + +If you want to contribute to @command{g77} by doing research, +design, specification, documentation, coding, or testing, +the following information should give you some ideas. + +@menu +* Efficiency:: Make @command{g77} itself compile code faster. +* Better Optimization:: Teach @command{g77} to generate faster code. +* Simplify Porting:: Make @command{g77} easier to configure, build, + and install. +* More Extensions:: Features many users won't know to ask for. +* Machine Model:: @command{g77} should better leverage @command{gcc}. +* Internals Documentation:: Make maintenance easier. +* Internals Improvements:: Make internals more robust. +* Better Diagnostics:: Make using @command{g77} on new code easier. +@end menu + +@node Efficiency +@section Improve Efficiency +@cindex efficiency + +Don't bother doing any performance analysis until most of the +following items are taken care of, because there's no question +they represent serious space/time problems, although some of +them show up only given certain kinds of (popular) input. + +@itemize @bullet +@item +Improve @code{malloc} package and its uses to specify more info about +memory pools and, where feasible, use obstacks to implement them. + +@item +Skip over uninitialized portions of aggregate areas (arrays, +@code{COMMON} areas, @code{EQUIVALENCE} areas) so zeros need not be output. +This would reduce memory usage for large initialized aggregate +areas, even ones with only one initialized element. + +As of version 0.5.18, a portion of this item has already been +accomplished. + +@item +Prescan the statement (in @file{sta.c}) so that the nature of the statement +is determined as much as possible by looking entirely at its form, +and not looking at any context (previous statements, including types +of symbols). +This would allow ripping out of the statement-confirmation, +symbol retraction/confirmation, and diagnostic inhibition +mechanisms. +Plus, it would result in much-improved diagnostics. +For example, @samp{CALL some-intrinsic(@dots{})}, where the intrinsic +is not a subroutine intrinsic, would result actual error instead of the +unimplemented-statement catch-all. + +@item +Throughout @command{g77}, don't pass line/column pairs where +a simple @code{ffewhere} type, which points to the error as much as is +desired by the configuration, will do, and don't pass @code{ffelexToken} types +where a simple @code{ffewhere} type will do. +Then, allow new default +configuration of @code{ffewhere} such that the source line text is not +preserved, and leave it to things like Emacs' next-error function +to point to them (now that @samp{next-error} supports column, +or, perhaps, character-offset, numbers). +The change in calling sequences should improve performance somewhat, +as should not having to save source lines. +(Whether this whole +item will improve performance is questionable, but it should +improve maintainability.) + +@item +Handle @samp{DATA (A(I),I=1,1000000)/1000000*2/} more efficiently, especially +as regards the assembly output. +Some of this might require improving +the back end, but lots of improvement in space/time required in @command{g77} +itself can be fairly easily obtained without touching the back end. +Maybe type-conversion, where necessary, can be speeded up as well in +cases like the one shown (converting the @samp{2} into @samp{2.}). + +@item +If analysis shows it to be worthwhile, optimize @file{lex.c}. + +@item +Consider redesigning @file{lex.c} to not need any feedback +during tokenization, by keeping track of enough parse state on its +own. +@end itemize + +@node Better Optimization +@section Better Optimization +@cindex optimization, better +@cindex code generation, improving + +Much of this work should be put off until after @command{g77} has +all the features necessary for its widespread acceptance as a +useful F77 compiler. +However, perhaps this work can be done in parallel during +the feature-adding work. + +@itemize @bullet +@item +Do the equivalent of the trick of putting @samp{extern inline} in front +of every function definition in @code{libg2c} and #include'ing the resulting +file in @command{f2c}+@command{gcc}---that is, inline all run-time-library functions +that are at all worth inlining. +(Some of this has already been done, such as for integral exponentiation.) + +@item +When doing @samp{CHAR_VAR = CHAR_FUNC(@dots{})}, +and it's clear that types line up +and @samp{CHAR_VAR} is addressable or not a @code{VAR_DECL}, +make @samp{CHAR_VAR}, not a +temporary, be the receiver for @samp{CHAR_FUNC}. +(This is now done for @code{COMPLEX} variables.) + +@item +Design and implement Fortran-specific optimizations that don't +really belong in the back end, or where the front end needs to +give the back end more info than it currently does. + +@item +Design and implement a new run-time library interface, with the +code going into @code{libgcc} so no special linking is required to +link Fortran programs using standard language features. +This library +would speed up lots of things, from I/O (using precompiled formats, +doing just one, or, at most, very few, calls for arrays or array sections, +and so on) to general computing (array/section implementations of +various intrinsics, implementation of commonly performed loops that +aren't likely to be optimally compiled otherwise, etc.). + +Among the important things the library would do are: + +@itemize @bullet +@item +Be a one-stop-shop-type +library, hence shareable and usable by all, in that what are now +library-build-time options in @code{libg2c} would be moved at least to the +@command{g77} compile phase, if not to finer grains (such as choosing how +list-directed I/O formatting is done by default at @code{OPEN} time, for +preconnected units via options or even statements in the main program +unit, maybe even on a per-I/O basis with appropriate pragma-like +devices). +@end itemize + +@item +Probably requiring the new library design, change interface to +normally have @code{COMPLEX} functions return their values in the way +@command{gcc} would if they were declared @code{__complex__ float}, +rather than using +the mechanism currently used by @code{CHARACTER} functions (whereby the +functions are compiled as returning void and their first arg is +a pointer to where to store the result). +(Don't append underscores to +external names for @code{COMPLEX} functions in some cases once @command{g77} uses +@command{gcc} rather than @command{f2c} calling conventions.) + +@item +Do something useful with @code{doiter} references where possible. +For example, @samp{CALL FOO(I)} cannot modify @samp{I} if within +a @code{DO} loop that uses @samp{I} as the +iteration variable, and the back end might find that info useful +in determining whether it needs to read @samp{I} back into a register after +the call. +(It normally has to do that, unless it knows @samp{FOO} never +modifies its passed-by-reference argument, which is rarely the case +for Fortran-77 code.) +@end itemize + +@node Simplify Porting +@section Simplify Porting +@cindex porting, simplify +@cindex simplify porting + +Making @command{g77} easier to configure, port, build, and install, either +as a single-system compiler or as a cross-compiler, would be +very useful. + +@itemize @bullet +@item +A new library (replacing @code{libg2c}) should improve portability as well as +produce more optimal code. +Further, @command{g77} and the new library should +conspire to simplify naming of externals, such as by removing unnecessarily +added underscores, and to reduce/eliminate the possibility of naming +conflicts, while making debugger more straightforward. + +Also, it should +make multi-language applications more feasible, such as by providing +Fortran intrinsics that get Fortran unit numbers given C @code{FILE *} +descriptors. + +@item +Possibly related to a new library, @command{g77} should produce the equivalent +of a @command{gcc} @samp{main(argc, argv)} function when it compiles a +main program unit, instead of compiling something that must be +called by a library +implementation of @code{main()}. + +This would do many useful things such as +provide more flexibility in terms of setting up exception handling, +not requiring programmers to start their debugging sessions with +@kbd{breakpoint MAIN__} followed by @kbd{run}, and so on. + +@item +The GBE needs to understand the difference between alignment +requirements and desires. +For example, on Intel x86 machines, @command{g77} currently imposes +overly strict alignment requirements, due to the back end, but it +would be useful for Fortran and C programmers to be able to override +these @emph{recommendations} as long as they don't violate the actual +processor @emph{requirements}. +@end itemize + +@node More Extensions +@section More Extensions +@cindex extensions, more + +These extensions are not the sort of things users ask for ``by name'', +but they might improve the usability of @command{g77}, and Fortran in +general, in the long run. +Some of these items really pertain to improving @command{g77} internals +so that some popular extensions can be more easily supported. + +@itemize @bullet +@item +Look through all the documentation on the GNU Fortran language, +dialects, compiler, missing features, bugs, and so on. +Many mentions of incomplete or missing features are +sprinkled throughout. +It is not worth repeating them here. + +@item +Consider adding a @code{NUMERIC} type to designate typeless numeric constants, +named and unnamed. +The idea is to provide a forward-looking, effective +replacement for things like the old-style @code{PARAMETER} statement +when people +really need typelessness in a maintainable, portable, clearly documented +way. +Maybe @code{TYPELESS} would include @code{CHARACTER}, @code{POINTER}, +and whatever else might come along. +(This is not really a call for polymorphism per se, just +an ability to express limited, syntactic polymorphism.) + +@item +Support @samp{OPEN(@dots{},KEY=(@dots{}),@dots{})}. + +@item +Support arbitrary file unit numbers, instead of limiting them +to 0 through @samp{MXUNIT-1}. +(This is a @code{libg2c} issue.) + +@item +@samp{OPEN(NOSPANBLOCKS,@dots{})} is treated as +@samp{OPEN(UNIT=NOSPANBLOCKS,@dots{})}, so a +later @code{UNIT=} in the first example is invalid. +Make sure this is what users of this feature would expect. + +@item +Currently @command{g77} disallows @samp{READ(1'10)} since +it is an obnoxious syntax, but +supporting it might be pretty easy if needed. +More details are needed, such +as whether general expressions separated by an apostrophe are supported, +or maybe the record number can be a general expression, and so on. + +@item +Support @code{STRUCTURE}, @code{UNION}, @code{MAP}, and @code{RECORD} +fully. +Currently there is no support at all +for @code{%FILL} in @code{STRUCTURE} and related syntax, +whereas the rest of the +stuff has at least some parsing support. +This requires either major +changes to @code{libg2c} or its replacement. + +@item +F90 and @command{g77} probably disagree about label scoping relative to +@code{INTERFACE} and @code{END INTERFACE}, and their contained +procedure interface bodies (blocks?). + +@item +@code{ENTRY} doesn't support F90 @code{RESULT()} yet, +since that was added after S8.112. + +@item +Empty-statement handling (10 ;;CONTINUE;;) probably isn't consistent +with the final form of the standard (it was vague at S8.112). + +@item +It seems to be an ``open'' question whether a file, immediately after being +@code{OPEN}ed,is positioned at the beginning, the end, or wherever---it +might be nice to offer an option of opening to ``undefined'' status, requiring +an explicit absolute-positioning operation to be performed before any +other (besides @code{CLOSE}) to assist in making applications port to systems +(some IBM?) that @code{OPEN} to the end of a file or some such thing. +@end itemize + +@node Machine Model +@section Machine Model + +This items pertain to generalizing @command{g77}'s view of +the machine model to more fully accept whatever the GBE +provides it via its configuration. + +@itemize @bullet +@item +Switch to using @code{REAL_VALUE_TYPE} to represent floating-point constants +exclusively so the target float format need not be required. +This +means changing the way @command{g77} handles initialization of aggregate areas +having more than one type, such as @code{REAL} and @code{INTEGER}, +because currently +it initializes them as if they were arrays of @code{char} and uses the +bit patterns of the constants of the various types in them to determine +what to stuff in elements of the arrays. + +@item +Rely more and more on back-end info and capabilities, especially in the +area of constants (where having the @command{g77} front-end's IL just store +the appropriate tree nodes containing constants might be best). + +@item +Suite of C and Fortran programs that a user/administrator can run on a +machine to help determine the configuration for @command{g77} before building +and help determine if the compiler works (especially with whatever +libraries are installed) after building. +@end itemize + +@node Internals Documentation +@section Internals Documentation + +Better info on how @command{g77} works and how to port it is needed. + +@xref{Front End}, which contains some information +on @command{g77} internals. + +@node Internals Improvements +@section Internals Improvements + +Some more items that would make @command{g77} more reliable +and easier to maintain: + +@itemize @bullet +@item +Generally make expression handling focus +more on critical syntax stuff, leaving semantics to callers. +For example, +anything a caller can check, semantically, let it do so, rather +than having @file{expr.c} do it. +(Exceptions might include things like +diagnosing @samp{FOO(I--K:)=BAR} where @samp{FOO} is a @code{PARAMETER}---if +it seems +important to preserve the left-to-right-in-source order of production +of diagnostics.) + +@item +Come up with better naming conventions for @option{-D} to establish requirements +to achieve desired implementation dialect via @file{proj.h}. + +@item +Clean up used tokens and @code{ffewhere}s in @code{ffeglobal_terminate_1}. + +@item +Replace @file{sta.c} @code{outpooldisp} mechanism with @code{malloc_pool_use}. + +@item +Check for @code{opANY} in more places in @file{com.c}, @file{std.c}, +and @file{ste.c}, and get rid of the @samp{opCONVERT(opANY)} kludge +(after determining if there is indeed no real need for it). + +@item +Utility to read and check @file{bad.def} messages and their references in the +code, to make sure calls are consistent with message templates. + +@item +Search and fix @samp{&ffe@dots{}} and similar so that +@samp{ffe@dots{}ptr@dots{}} macros are +available instead (a good argument for wishing this could have written all +this stuff in C++, perhaps). +On the other hand, it's questionable whether this sort of +improvement is really necessary, given the availability of +tools such as Emacs and Perl, which make finding any +address-taking of structure members easy enough? + +@item +Some modules truly export the member names of their structures (and the +structures themselves), maybe fix this, and fix other modules that just +appear to as well (by appending @samp{_}, though it'd be ugly and probably +not worth the time). + +@item +Implement C macros @samp{RETURNS(value)} and @samp{SETS(something,value)} +in @file{proj.h} +and use them throughout @command{g77} source code (especially in the definitions +of access macros in @samp{.h} files) so they can be tailored +to catch code writing into a @samp{RETURNS()} or reading from a @samp{SETS()}. + +@item +Decorate throughout with @code{const} and other such stuff. + +@item +All F90 notational derivations in the source code are still based +on the S8.112 version of the draft standard. +Probably should update +to the official standard, or put documentation of the rules as used +in the code@dots{}uh@dots{}in the code. + +@item +Some @code{ffebld_new} calls (those outside of @file{ffeexpr.c} or +inside but invoked via paths not involving @code{ffeexpr_lhs} or +@code{ffeexpr_rhs}) might be creating things +in improper pools, leading to such things staying around too long or +(doubtful, but possible and dangerous) not long enough. + +@item +Some @code{ffebld_list_new} (or whatever) calls might not be matched by +@code{ffebld_list_bottom} (or whatever) calls, which might someday matter. +(It definitely is not a problem just yet.) + +@item +Probably not doing clean things when we fail to @code{EQUIVALENCE} something +due to alignment/mismatch or other problems---they end up without +@code{ffestorag} objects, so maybe the backend (and other parts of the front +end) can notice that and handle like an @code{opANY} (do what it wants, just +don't complain or crash). +Most of this seems to have been addressed +by now, but a code review wouldn't hurt. +@end itemize + +@node Better Diagnostics +@section Better Diagnostics + +These are things users might not ask about, or that need to +be looked into, before worrying about. +Also here are items that involve reducing unnecessary diagnostic +clutter. + +@itemize @bullet +@item +When @code{FUNCTION} and @code{ENTRY} point types disagree (@code{CHARACTER} +lengths, type classes, and so on), +@code{ANY}-ize the offending @code{ENTRY} point and any @emph{new} dummies +it specifies. + +@item +Speed up and improve error handling for data when repeat-count is +specified. +For example, don't output 20 unnecessary messages after the +first necessary one for: + +@smallexample +INTEGER X(20) +CONTINUE +DATA (X(I), J= 1, 20) /20*5/ +END +@end smallexample + +@noindent +(The @code{CONTINUE} statement ensures the @code{DATA} statement +is processed in the context of executable, not specification, +statements.) +@end itemize + +@include ffe.texi + +@end ifset + +@ifset USING +@node Diagnostics +@chapter Diagnostics +@cindex diagnostics + +Some diagnostics produced by @command{g77} require sufficient explanation +that the explanations are given below, and the diagnostics themselves +identify the appropriate explanation. + +Identification uses the GNU Info format---specifically, the @command{info} +command that displays the explanation is given within square +brackets in the diagnostic. +For example: + +@smallexample +foo.f:5: Invalid statement [info -f g77 M FOOEY] +@end smallexample + +More details about the above diagnostic is found in the @command{g77} Info +documentation, menu item @samp{M}, submenu item @samp{FOOEY}, +which is displayed by typing the UNIX command +@samp{info -f g77 M FOOEY}. + +Other Info readers, such as EMACS, may be just as easily used to display +the pertinent node. +In the above example, @samp{g77} is the Info document name, +@samp{M} is the top-level menu item to select, +and, in that node (named @samp{Diagnostics}, the name of +this chapter, which is the very text you're reading now), +@samp{FOOEY} is the menu item to select. + +@iftex +In this printed version of the @command{g77} manual, the above example +points to a section, below, entitled @samp{FOOEY}---though, of course, +as the above is just a sample, no such section exists. +@end iftex + +@menu +* CMPAMBIG:: Ambiguous use of intrinsic. +* EXPIMP:: Intrinsic used explicitly and implicitly. +* INTGLOB:: Intrinsic also used as name of global. +* LEX:: Various lexer messages +* GLOBALS:: Disagreements about globals. +* LINKFAIL:: When linking @code{f771} fails. +* Y2KBAD:: Use of non-Y2K-compliant intrinsic. +@end menu + +@node CMPAMBIG +@section @code{CMPAMBIG} + +@noindent +@smallexample +Ambiguous use of intrinsic @var{intrinsic} @dots{} +@end smallexample + +The type of the argument to the invocation of the @var{intrinsic} +intrinsic is a @code{COMPLEX} type other than @code{COMPLEX(KIND=1)}. +Typically, it is @code{COMPLEX(KIND=2)}, also known as +@code{DOUBLE COMPLEX}. + +The interpretation of this invocation depends on the particular +dialect of Fortran for which the code was written. +Some dialects convert the real part of the argument to +@code{REAL(KIND=1)}, thus losing precision; other dialects, +and Fortran 90, do no such conversion. + +So, GNU Fortran rejects such invocations except under certain +circumstances, to avoid making an incorrect assumption that results +in generating the wrong code. + +To determine the dialect of the program unit, perhaps even whether +that particular invocation is properly coded, determine how the +result of the intrinsic is used. + +The result of @var{intrinsic} is expected (by the original programmer) +to be @code{REAL(KIND=1)} (the non-Fortran-90 interpretation) if: + +@itemize @bullet +@item +It is passed as an argument to a procedure that explicitly or +implicitly declares that argument @code{REAL(KIND=1)}. + +For example, +a procedure with no @code{DOUBLE PRECISION} or @code{IMPLICIT DOUBLE PRECISION} +statement specifying the dummy argument corresponding to an +actual argument of @samp{REAL(Z)}, where @samp{Z} is declared +@code{DOUBLE COMPLEX}, strongly suggests that the programmer +expected @samp{REAL(Z)} to return @code{REAL(KIND=1)} instead +of @code{REAL(KIND=2)}. + +@item +It is used in a context that would otherwise not include +any @code{REAL(KIND=2)} but where treating the @var{intrinsic} +invocation as @code{REAL(KIND=2)} would result in unnecessary +promotions and (typically) more expensive operations on the +wider type. + +For example: + +@smallexample +DOUBLE COMPLEX Z +@dots{} +R(1) = T * REAL(Z) +@end smallexample + +The above example suggests the programmer expected the real part +of @samp{Z} to be converted to @code{REAL(KIND=1)} before being +multiplied by @samp{T} (presumed, along with @samp{R} above, to +be type @code{REAL(KIND=1)}). + +Otherwise, the conversion would have to be delayed until after +the multiplication, requiring not only an extra conversion +(of @samp{T} to @code{REAL(KIND=2)}), but a (typically) more +expensive multiplication (a double-precision multiplication instead +of a single-precision one). +@end itemize + +The result of @var{intrinsic} is expected (by the original programmer) +to be @code{REAL(KIND=2)} (the Fortran 90 interpretation) if: + +@itemize @bullet +@item +It is passed as an argument to a procedure that explicitly or +implicitly declares that argument @code{REAL(KIND=2)}. + +For example, a procedure specifying a @code{DOUBLE PRECISION} +dummy argument corresponding to an +actual argument of @samp{REAL(Z)}, where @samp{Z} is declared +@code{DOUBLE COMPLEX}, strongly suggests that the programmer +expected @samp{REAL(Z)} to return @code{REAL(KIND=2)} instead +of @code{REAL(KIND=1)}. + +@item +It is used in an expression context that includes +other @code{REAL(KIND=2)} operands, +or is assigned to a @code{REAL(KIND=2)} variable or array element. + +For example: + +@smallexample +DOUBLE COMPLEX Z +DOUBLE PRECISION R, T +@dots{} +R(1) = T * REAL(Z) +@end smallexample + +The above example suggests the programmer expected the real part +of @samp{Z} to @emph{not} be converted to @code{REAL(KIND=1)} +by the @code{REAL()} intrinsic. + +Otherwise, the conversion would have to be immediately followed +by a conversion back to @code{REAL(KIND=2)}, losing +the original, full precision of the real part of @code{Z}, +before being multiplied by @samp{T}. +@end itemize + +Once you have determined whether a particular invocation of @var{intrinsic} +expects the Fortran 90 interpretation, you can: + +@itemize @bullet +@item +Change it to @samp{DBLE(@var{expr})} (if @var{intrinsic} is +@code{REAL}) or @samp{DIMAG(@var{expr})} (if @var{intrinsic} +is @code{AIMAG}) +if it expected the Fortran 90 interpretation. + +This assumes @var{expr} is @code{COMPLEX(KIND=2)}---if it is +some other type, such as @code{COMPLEX*32}, you should use the +appropriate intrinsic, such as the one to convert to @code{REAL*16} +(perhaps @code{DBLEQ()} in place of @code{DBLE()}, and +@code{QIMAG()} in place of @code{DIMAG()}). + +@item +Change it to @samp{REAL(@var{intrinsic}(@var{expr}))}, +otherwise. +This converts to @code{REAL(KIND=1)} in all working +Fortran compilers. +@end itemize + +If you don't want to change the code, and you are certain that all +ambiguous invocations of @var{intrinsic} in the source file have +the same expectation regarding interpretation, you can: + +@itemize @bullet +@item +Compile with the @command{g77} option @option{-ff90}, to enable the +Fortran 90 interpretation. + +@item +Compile with the @command{g77} options @samp{-fno-f90 -fugly-complex}, +to enable the non-Fortran-90 interpretations. +@end itemize + +@xref{REAL() and AIMAG() of Complex}, for more information on this +issue. + +Note: If the above suggestions don't produce enough evidence +as to whether a particular program expects the Fortran 90 +interpretation of this ambiguous invocation of @var{intrinsic}, +there is one more thing you can try. + +If you have access to most or all the compilers used on the +program to create successfully tested and deployed executables, +read the documentation for, and @emph{also} test out, each compiler +to determine how it treats the @var{intrinsic} intrinsic in +this case. +(If all the compilers don't agree on an interpretation, there +might be lurking bugs in the deployed versions of the program.) + +The following sample program might help: + +@cindex JCB003 program +@smallexample + PROGRAM JCB003 +C +C Written by James Craig Burley 1997-02-23. +C +C Determine how compilers handle non-standard REAL +C and AIMAG on DOUBLE COMPLEX operands. +C + DOUBLE COMPLEX Z + REAL R + Z = (3.3D0, 4.4D0) + R = Z + CALL DUMDUM(Z, R) + R = REAL(Z) - R + IF (R .NE. 0.) PRINT *, 'REAL() is Fortran 90' + IF (R .EQ. 0.) PRINT *, 'REAL() is not Fortran 90' + R = 4.4D0 + CALL DUMDUM(Z, R) + R = AIMAG(Z) - R + IF (R .NE. 0.) PRINT *, 'AIMAG() is Fortran 90' + IF (R .EQ. 0.) PRINT *, 'AIMAG() is not Fortran 90' + END +C +C Just to make sure compiler doesn't use naive flow +C analysis to optimize away careful work above, +C which might invalidate results.... +C + SUBROUTINE DUMDUM(Z, R) + DOUBLE COMPLEX Z + REAL R + END +@end smallexample + +If the above program prints contradictory results on a +particular compiler, run away! + +@node EXPIMP +@section @code{EXPIMP} + +@noindent +@smallexample +Intrinsic @var{intrinsic} referenced @dots{} +@end smallexample + +The @var{intrinsic} is explicitly declared in one program +unit in the source file and implicitly used as an intrinsic +in another program unit in the same source file. + +This diagnostic is designed to catch cases where a program +might depend on using the name @var{intrinsic} as an intrinsic +in one program unit and as a global name (such as the name +of a subroutine or function) in another, but @command{g77} recognizes +the name as an intrinsic in both cases. + +After verifying that the program unit making implicit use +of the intrinsic is indeed written expecting the intrinsic, +add an @samp{INTRINSIC @var{intrinsic}} statement to that +program unit to prevent this warning. + +This and related warnings are disabled by using +the @option{-Wno-globals} option when compiling. + +Note that this warning is not issued for standard intrinsics. +Standard intrinsics include those described in the FORTRAN 77 +standard and, if @option{-ff90} is specified, those described +in the Fortran 90 standard. +Such intrinsics are not as likely to be confused with user +procedures as intrinsics provided as extensions to the +standard by @command{g77}. + +@node INTGLOB +@section @code{INTGLOB} + +@noindent +@smallexample +Same name `@var{intrinsic}' given @dots{} +@end smallexample + +The name @var{intrinsic} is used for a global entity (a common +block or a program unit) in one program unit and implicitly +used as an intrinsic in another program unit. + +This diagnostic is designed to catch cases where a program +intends to use a name entirely as a global name, but @command{g77} +recognizes the name as an intrinsic in the program unit that +references the name, a situation that would likely produce +incorrect code. + +For example: + +@smallexample +INTEGER FUNCTION TIME() +@dots{} +END +@dots{} +PROGRAM SAMP +INTEGER TIME +PRINT *, 'Time is ', TIME() +END +@end smallexample + +The above example defines a program unit named @samp{TIME}, but +the reference to @samp{TIME} in the main program unit @samp{SAMP} +is normally treated by @command{g77} as a reference to the intrinsic +@code{TIME()} (unless a command-line option that prevents such +treatment has been specified). + +As a result, the program @samp{SAMP} will @emph{not} +invoke the @samp{TIME} function in the same source file. + +Since @command{g77} recognizes @code{libU77} procedures as +intrinsics, and since some existing code uses the same names +for its own procedures as used by some @code{libU77} +procedures, this situation is expected to arise often enough +to make this sort of warning worth issuing. + +After verifying that the program unit making implicit use +of the intrinsic is indeed written expecting the intrinsic, +add an @samp{INTRINSIC @var{intrinsic}} statement to that +program unit to prevent this warning. + +Or, if you believe the program unit is designed to invoke the +program-defined procedure instead of the intrinsic (as +recognized by @command{g77}), add an @samp{EXTERNAL @var{intrinsic}} +statement to the program unit that references the name to +prevent this warning. + +This and related warnings are disabled by using +the @option{-Wno-globals} option when compiling. + +Note that this warning is not issued for standard intrinsics. +Standard intrinsics include those described in the FORTRAN 77 +standard and, if @option{-ff90} is specified, those described +in the Fortran 90 standard. +Such intrinsics are not as likely to be confused with user +procedures as intrinsics provided as extensions to the +standard by @command{g77}. + +@node LEX +@section @code{LEX} + +@noindent +@smallexample +Unrecognized character @dots{} +Invalid first character @dots{} +Line too long @dots{} +Non-numeric character @dots{} +Continuation indicator @dots{} +Label at @dots{} invalid with continuation line indicator @dots{} +Character constant @dots{} +Continuation line @dots{} +Statement at @dots{} begins with invalid token +@end smallexample + +Although the diagnostics identify specific problems, they can +be produced when general problems such as the following occur: + +@itemize @bullet +@item +The source file contains something other than Fortran code. + +If the code in the file does not look like many of the examples +elsewhere in this document, it might not be Fortran code. +(Note that Fortran code often is written in lower case letters, +while the examples in this document use upper case letters, +for stylistic reasons.) + +For example, if the file contains lots of strange-looking +characters, it might be APL source code; if it contains lots +of parentheses, it might be Lisp source code; if it +contains lots of bugs, it might be C++ source code. + +@item +The source file contains free-form Fortran code, but @option{-ffree-form} +was not specified on the command line to compile it. + +Free form is a newer form for Fortran code. +The older, classic form is called fixed form. + +@cindex continuation character +@cindex characters, continuation +Fixed-form code is visually fairly distinctive, because +numerical labels and comments are all that appear in +the first five columns of a line, the sixth column is +reserved to denote continuation lines, +and actual statements start at or beyond column 7. +Spaces generally are not significant, so if you +see statements such as @samp{REALX,Y} and @samp{DO10I=1,100}, +you are looking at fixed-form code. +@cindex * +@cindex asterisk +Comment lines are indicated by the letter @samp{C} or the symbol +@samp{*} in column 1. +@cindex trailing comment +@cindex comment +@cindex characters, comment +@cindex ! +@cindex exclamation point +(Some code uses @samp{!} or @samp{/*} to begin in-line comments, +which many compilers support.) + +Free-form code is distinguished from fixed-form source +primarily by the fact that statements may start anywhere. +(If lots of statements start in columns 1 through 6, +that's a strong indicator of free-form source.) +Consecutive keywords must be separated by spaces, so +@samp{REALX,Y} is not valid, while @samp{REAL X,Y} is. +There are no comment lines per se, but @samp{!} starts a +comment anywhere in a line (other than within a character or +Hollerith constant). + +@xref{Source Form}, for more information. + +@item +The source file is in fixed form and has been edited without +sensitivity to the column requirements. + +Statements in fixed-form code must be entirely contained within +columns 7 through 72 on a given line. +Starting them ``early'' is more likely to result in diagnostics +than finishing them ``late'', though both kinds of errors are +often caught at compile time. + +For example, if the following code fragment is edited by following +the commented instructions literally, the result, shown afterward, +would produce a diagnostic when compiled: + +@smallexample +C On XYZZY systems, remove "C" on next line: +C CALL XYZZY_RESET +@end smallexample + +The result of editing the above line might be: + +@smallexample +C On XYZZY systems, remove "C" on next line: + CALL XYZZY_RESET +@end smallexample + +However, that leaves the first @samp{C} in the @code{CALL} +statement in column 6, making it a comment line, which is +not really what the author intended, and which is likely +to result in one of the above-listed diagnostics. + +@emph{Replacing} the @samp{C} in column 1 with a space +is the proper change to make, to ensure the @code{CALL} +keyword starts in or after column 7. + +Another common mistake like this is to forget that fixed-form +source lines are significant through only column 72, and that, +normally, any text beyond column 72 is ignored or is diagnosed +at compile time. + +@xref{Source Form}, for more information. + +@item +The source file requires preprocessing, and the preprocessing +is not being specified at compile time. + +A source file containing lines beginning with @code{#define}, +@code{#include}, @code{#if}, and so on is likely one that +requires preprocessing. + +If the file's suffix is @samp{.f}, @samp{.for}, or @samp{.FOR}, +the file normally will be compiled @emph{without} preprocessing +by @command{g77}. + +Change the file's suffix from @samp{.f} to @samp{.F} +(or, on systems with case-insensitive file names, +to @samp{.fpp} or @samp{.FPP}), +from @samp{.for} to @samp{.fpp}, +or from @samp{.FOR} to @samp{.FPP}. +@command{g77} compiles files with such names @emph{with} +preprocessing. + +@pindex cpp +@cindex preprocessor +@cindex cpp program +@cindex programs, cpp +@cindex @option{-x f77-cpp-input} option +@cindex options, @option{-x f77-cpp-input} +Or, learn how to use @command{gcc}'s @option{-x} option to specify +the language @samp{f77-cpp-input} for Fortran files that +require preprocessing. +@xref{Overall Options,,Options Controlling the Kind of +Output,gcc,Using the GNU Compiler Collection (GCC)}. + +@item +The source file is preprocessed, and the results of preprocessing +result in syntactic errors that are not necessarily obvious to +someone examining the source file itself. + +Examples of errors resulting from preprocessor macro expansion +include exceeding the line-length limit, improperly starting, +terminating, or incorporating the apostrophe or double-quote in +a character constant, improperly forming a Hollerith constant, +and so on. + +@xref{Overall Options,,Options Controlling the Kind of Output}, +for suggestions about how to use, and not use, preprocessing +for Fortran code. +@end itemize + +@node GLOBALS +@section @code{GLOBALS} + +@noindent +@smallexample +Global name @var{name} defined at @dots{} already defined@dots{} +Global name @var{name} at @dots{} has different type@dots{} +Too many arguments passed to @var{name} at @dots{} +Too few arguments passed to @var{name} at @dots{} +Argument #@var{n} of @var{name} is @dots{} +@end smallexample + +These messages all identify disagreements about the +global procedure named @var{name} among different program units +(usually including @var{name} itself). + +Whether a particular disagreement is reported +as a warning or an error +can depend on the relative order +of the disagreeing portions of the source file. + +Disagreements between a procedure invocation +and the @emph{subsequent} procedure itself +are, usually, diagnosed as errors +when the procedure itself @emph{precedes} the invocation. +Other disagreements are diagnosed via warnings. + +@cindex forward references +@cindex in-line code +@cindex compilation, in-line +This distinction, between warnings and errors, +is due primarily to the present tendency of the @command{gcc} back end +to inline only those procedure invocations that are +@emph{preceded} by the corresponding procedure definitions. +If the @command{gcc} back end is changed +to inline ``forward references'', +in which invocations precede definitions, +the @command{g77} front end will be changed +to treat both orderings as errors, accordingly. + +The sorts of disagreements that are diagnosed by @command{g77} include +whether a procedure is a subroutine or function; +if it is a function, the type of the return value of the procedure; +the number of arguments the procedure accepts; +and the type of each argument. + +Disagreements regarding global names among program units +in a Fortran program @emph{should} be fixed in the code itself. +However, if that is not immediately practical, +and the code has been working for some time, +it is possible it will work +when compiled with the @option{-fno-globals} option. + +The @option{-fno-globals} option +causes these diagnostics to all be warnings +and disables all inlining of references to global procedures +(to avoid subsequent compiler crashes and bad-code generation). +Use of the @option{-Wno-globals} option as well as @option{-fno-globals} +suppresses all of these diagnostics. +(@option{-Wno-globals} by itself disables only the warnings, +not the errors.) + +After using @option{-fno-globals} to work around these problems, +it is wise to stop using that option and address them by fixing +the Fortran code, because such problems, while they might not +actually result in bugs on some systems, indicate that the code +is not as portable as it could be. +In particular, the code might appear to work on a particular +system, but have bugs that affect the reliability of the data +without exhibiting any other outward manifestations of the bugs. + +@node LINKFAIL +@section @code{LINKFAIL} + +@noindent +On AIX 4.1, @command{g77} might not build with the native (non-GNU) tools +due to a linker bug in coping with the @option{-bbigtoc} option which +leads to a @samp{Relocation overflow} error. The GNU linker is not +recommended on current AIX versions, though; it was developed under a +now-unsupported version. This bug is said to be fixed by `update PTF +U455193 for APAR IX75823'. + +Compiling with @option{-mminimal-toc} +might solve this problem, e.g.@: by adding +@smallexample +BOOT_CFLAGS='-mminimal-toc -O2 -g' +@end smallexample +to the @code{make bootstrap} command line. + +@node Y2KBAD +@section @code{Y2KBAD} +@cindex Y2K compliance +@cindex Year 2000 compliance + +@noindent +@smallexample +Intrinsic `@var{name}', invoked at (^), known to be non-Y2K-compliant@dots{} +@end smallexample + +This diagnostic indicates that +the specific intrinsic invoked by the name @var{name} +is known to have an interface +that is not Year-2000 (Y2K) compliant. + +@xref{Year 2000 (Y2K) Problems}. + +@end ifset + +@node Keyword Index +@unnumbered Keyword Index + +@printindex cp +@bye |
