| \input texinfo @c -*-texinfo-*- |
| @c %**start of header |
| @setfilename g77.info |
| |
| @set last-update 2002-02-01 |
| @set copyrights-g77 1995,1996,1997,1998,1999,2000,2001,2002 |
| |
| @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 |
| |
| @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition. (from gcc.texi) |
| @c @smallbook |
| |
| @c i also commented out the finalout command, so if there *are* any |
| @c overfulls, you'll (hopefully) see the rectangle in the right hand |
| @c margin. -- burley 1999-03-13 (from mew's comment in gcc.texi). |
| @c @finalout |
| |
| @macro gcctabopt{body} |
| @code{\body\} |
| @end macro |
| @macro gccoptlist{body} |
| @smallexample |
| \body\ |
| @end smallexample |
| @end macro |
| @c Makeinfo handles the above macro OK, TeX needs manual line breaks; |
| @c they get lost at some point in handling the macro. But if @macro is |
| @c used here rather than @alias, it produces double line breaks. |
| @iftex |
| @alias gol = * |
| @end iftex |
| @ifnottex |
| @macro gol |
| @end macro |
| @end ifnottex |
| |
| @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 |
| |
| @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 |
| |
| Copyright (C) @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.1 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 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 |
| @c @finalout |
| @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{version-g77} |
| @page |
| @vskip 0pt plus 1filll |
| Copyright @copyright{} @value{copyrights-g77} Free Software Foundation, Inc. |
| @sp 2 |
| 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 |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.1 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 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}. |
| |
| * 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 GNU CC 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. |
| |
| @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,,Compile C; C++; Objective-C; Ada; CHILL; Fortran; |
| or Java,gcc,Using the GNU Compiler Collection (GCC)}, |
| for information on the way different languages are handled |
| by the GNU CC 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/fortran/Books/}. 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, heterogenous 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 take care |
| of this when generating skeletons or prototype files as above, and also |
| 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 |
| non-zero 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). |
| |
| However, due to apparent bugs in the back end, @command{g77} currently doesn't |
| take advantage of this facility at all---it doesn't emit any debugging |
| information for @code{COMMON} and @code{EQUIVALENCE} areas, |
| other than information |
| on the array of @code{char} it creates (and, in the case |
| of local @code{EQUIVALENCE}, names) for each such area. |
| |
| 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 |
| assocation'', 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). |
| |
| @cindex alignment testing |
| @cindex testing alignment |
| A package that tests the degree to which a Fortran compiler |
| (such as @command{g77}) |
| aligns 64-bit floating-point variables and arrays |
| is available at @uref{ftp://alpha.gnu.org/gnu/g77/align/}. |
| |
| @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. |
| |
| To find out about major bugs discovered in the current release and |
| possible workarounds for them, see |
| @uref{ftp://alpha.gnu.org/g77.plan}. |
| |
| (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 behaviour. |
| 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/}, |
| and there is a supplemented version, in PostScript form, at |
| @uref{http://www.validgh.com/goldberg/paper.ps}. |
| |
| Information related to the IEEE 754 |
| floating-point standard by a leading light can be found at |
| @uref{http://http.cs.berkeley.edu/%7Ewkahan/ieee754status/}; |
| see also slides from the short course referenced from |
| @uref{http://http.cs.berkeley.edu/%7Efateman/}. |
| @uref{http://www.linuxsupportline.com/%7Ebillm/} has a brief |
| guide to IEEE 754, a somewhat x86-GNU/Linux-specific FAQ, |
| and library code for GNU/Linux x86 systems. |
| |
| The supplement to the PostScript-formatted Goldberg document, |
| referenced above, is available in HTML format. |
| See `Differences Among IEEE 754 Implementations' by Doug Priest, |
| available online at |
| @uref{http://www.validgh.com/goldberg/addendum.html}. |
| 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 behaviour is normally inherited from the system-dependent startup |
| code, though some targets, such as the Alpha, have code generation |
| options which change the behaviour. |
| |
| 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. |
| |
| Reporting a bug might help you by bringing a solution to your problem, or |
| it might not. |
| (If it does not, look in the service directory; see |
| @ref{Service}.) |
| In any case, the principal function of a bug report is |
| to help the entire community by making the next version of GNU Fortran work |
| better. |
| Bug reports are your contribution to the maintenance of GNU Fortran. |
| |
| Since the maintainers are very overloaded, we cannot respond to every |
| bug report. |
| However, if the bug has not been fixed, we are likely to |
| send you a patch and ask you to tell us whether it works. |
| |
| In order for a bug report to serve its purpose, you must include the |
| information that makes for fixing the bug. |
| |
| @menu |
| * Criteria: Bug Criteria. Have you really found a bug? |
| * Where: Bug Lists. Where to send your bug report. |
| * 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 Lists |
| @section Where to Report Bugs |
| @cindex bug report mailing lists |
| @kindex @value{email-bugs} |
| Send bug reports for GNU Fortran to @email{@value{email-bugs}}. |
| |
| Often people think of posting bug reports to a newsgroup instead of |
| mailing them. |
| This sometimes appears to work, but it has one problem which can be |
| crucial: a newsgroup posting does not contain a mail path back to the |
| sender. |
| Thus, if maintainers need more information, they might be unable |
| to reach you. For this reason, you should always send bug reports by |
| mail to the proper mailing list. |
| |
| As a last resort, send bug reports on paper to: |
| |
| @example |
| GNU Compiler Bugs |
| Free Software Foundation |
| 59 Temple Place - Suite 330 |
| Boston, MA 02111-1307, USA |
| @end example |
| |
| @node Bug Reporting |
| @section How to Report Bugs |
| @cindex compiler bugs, reporting |
| |
| The fundamental principle of reporting bugs usefully is this: |
| @strong{report all the facts}. |
| If you are not sure whether to state a |
| fact or leave it out, state it! |
| |
| Often people omit facts because they think they know what causes the |
| problem and they conclude that some details don't matter. |
| Thus, you might |
| assume that the name of the variable you use in an example does not matter. |
| Well, probably it doesn't, but one cannot be sure. |
| Perhaps the bug is a |
| stray memory reference which happens to fetch from the location where that |
| name is stored in memory; perhaps, if the name were different, the contents |
| of that location would fool the compiler into doing the right thing despite |
| the bug. |
| Play it safe and give a specific, complete example. |
| That is the |
| easiest thing for you to do, and the most helpful. |
| |
| Keep in mind that the purpose of a bug report is to enable someone to |
| fix the bug if it is not known. |
| It isn't very important what happens if |
| the bug is already known. |
| Therefore, always write your bug reports on |
| the assumption that the bug is not known. |
| |
| Sometimes people give a few sketchy facts and ask, ``Does this ring a |
| bell?'' |
| This cannot help us fix a bug, so it is rarely helpful. |
| We respond by asking for enough details to enable us to investigate. |
| You might as well expedite matters by sending them to begin with. |
| (Besides, there are enough bells ringing around here as it is.) |
| |
| Try to make your bug report self-contained. |
| If we have to ask you for |
| more information, it is best if you include all the previous information |
| in your response, as well as the information that was missing. |
| |
| Please report each bug in a separate message. |
| This makes it easier for |
| us to track which bugs have been fixed and to forward your bugs reports |
| to the appropriate maintainer. |
| |
| Do not compress and encode any part of your bug report using programs |
| such as @file{uuencode}. |
| If you do so it will slow down the processing |
| of your bug. |
| If you must submit multiple large files, use @file{shar}, |
| which allows us to read your message without having to run any |
| decompression programs. |
| |
| (As a special exception for GNU Fortran bug-reporting, at least |
| for now, if you are sending more than a few lines of code, if |
| your program's source file format contains ``interesting'' things |
| like trailing spaces or strange characters, or if you need to |
| include binary data files, it is acceptable to put all the |
| files together in a @command{tar} archive, and, whether you need to |
| do that, it is acceptable to then compress the single file (@command{tar} |
| archive or source file) |
| using @command{gzip} and encode it via @command{uuencode}. |
| Do not use any MIME stuff---the current maintainer can't decode this. |
| Using @command{compress} instead of @command{gzip} is acceptable, assuming |
| you have licensed the use of the patented algorithm in |
| @command{compress} from Unisys.) |
| |
| To enable someone to investigate the bug, you should include all these |
| things: |
| |
| @itemize @bullet |
| @item |
| The version of GNU Fortran. |
| You can get this by running @command{g77} with the @option{-v} option. |
| (Ignore any error messages that might be displayed |
| when the linker is run.) |
| |
| Without this, we won't know whether there is any point in looking for |
| the bug in the current version of GNU Fortran. |
| |
| @item |
| @cindex preprocessor |
| @cindex cpp program |
| @cindex programs, cpp |
| @pindex cpp |
| A complete input file that will reproduce the bug. |
| |
| If your source file(s) require preprocessing |
| (for example, their names have suffixes like |
| @samp{.F}, @samp{.fpp}, @samp{.FPP}, and @samp{.r}), |
| and the bug is in the compiler proper (@file{f771}) |
| or in a subsequent phase of processing, |
| run your source file through the C preprocessor |
| by doing @samp{g77 -E @var{sourcefile} > @var{newfile}}. |
| Then, include the contents of @var{newfile} in the bug report. |
| (When you do this, use the same preprocessor options---such as |
| @option{-I}, @option{-D}, and @option{-U}---that you used in actual |
| compilation.) |
| |
| A single statement is not enough of an example. |
| In order to compile it, |
| it must be embedded in a complete file of compiler input. |
| The bug might depend on the details of how this is done. |
| |
| Without a real example one can compile, |
| all anyone can do about your bug report is wish you luck. |
| It would be futile to try to guess how to provoke the bug. |
| For example, bugs in register allocation and reloading |
| can depend on every little detail of the source and include files |
| that trigger them. |
| |
| @item |
| @cindex included files |
| @cindex INCLUDE directive |
| @cindex directive, INCLUDE |
| @cindex #include directive |
| @cindex directive, #include |
| Note that you should include with your bug report any files |
| included by the source file |
| (via the @code{#include} or @code{INCLUDE} directive) |
| that you send, and any files they include, and so on. |
| |
| It is not necessary to replace |
| the @code{#include} and @code{INCLUDE} directives |
| with the actual files in the version of the source file that |
| you send, but it might make submitting the bug report easier |
| in the end. |
| However, be sure to @emph{reproduce} the bug using the @emph{exact} |
| version of the source material you submit, to avoid wild-goose |
| chases. |
| |
| @item |
| The command arguments you gave GNU Fortran to compile that example |
| and observe the bug. For example, did you use @option{-O}? To guarantee |
| you won't omit something important, list all the options. |
| |
| If we were to try to guess the arguments, we would probably guess wrong |
| and then we would not encounter the bug. |
| |
| @item |
| The type of machine you are using, and the operating system name and |
| version number. |
| (Much of this information is printed by @samp{g77 -v}---if you |
| include that, send along any additional info you have that you |
| don't see clearly represented in that output.) |
| |
| @item |
| The operands you gave to the @command{configure} command when you installed |
| the compiler. |
| |
| @item |
| A complete list of any modifications you have made to the compiler |
| source. (We don't promise to investigate the bug unless it happens in |
| an unmodified compiler. But if you've made modifications and don't tell |
| us, then you are sending us on a wild-goose chase.) |
| |
| Be precise about these changes. A description in English is not |
| enough---send a context diff for them. |
| |
| Adding files of your own (such as a machine description for a machine we |
| don't support) is a modification of the compiler source. |
| |
| @item |
| Details of any other deviations from the standard procedure for installing |
| GNU Fortran. |
| |
| @item |
| A description of what behavior you observe that you believe is |
| incorrect. For example, ``The compiler gets a fatal signal,'' or, |
| ``The assembler instruction at line 208 in the output is incorrect.'' |
| |
| Of course, if the bug is that the compiler gets a fatal signal, then one |
| can't miss it. But if the bug is incorrect output, the maintainer might |
| not notice unless it is glaringly wrong. None of us has time to study |
| all the assembler code from a 50-line Fortran program just on the chance that |
| one instruction might be wrong. We need @emph{you} to do this part! |
| |
| Even if the problem you experience is a fatal signal, you should still |
| say so explicitly. Suppose something strange is going on, such as, your |
| copy of the compiler is out of synch, or you have encountered a bug in |
| the C library on your system. (This has happened!) Your copy might |
| crash and the copy here would not. If you @i{said} to expect a crash, |
| then when the compiler here fails to crash, we would know that the bug |
| was not happening. If you don't say to expect a crash, then we would |
| not know whether the bug was happening. We would not be able to draw |
| any conclusion from our observations. |
| |
| If the problem is a diagnostic when building GNU Fortran with some other |
| compiler, say whether it is a warning or an error. |
| |
| Often the observed symptom is incorrect output when your program is run. |
| Sad to say, this is not enough information unless the program is short |
| and simple. None of us has time to study a large program to figure out |
| how it would work if compiled correctly, much less which line of it was |
| compiled wrong. So you will have to do that. Tell us which source line |
| it is, and what incorrect result happens when that line is executed. A |
| person who understands the program can find this as easily as finding a |
| bug in the program itself. |
| |
| @item |
| If you send examples of assembler code output from GNU Fortran, |
| please use @option{-g} when you make them. The debugging information |
| includes source line numbers which are essential for correlating the |
| output with the input. |
| |
| @item |
| If you wish to mention something in the GNU Fortran source, refer to it by |
| context, not by line number. |
| |
| The line numbers in the development sources don't match those in your |
| sources. Your line numbers would convey no convenient information to the |
| maintainers. |
| |
| @item |
| Additional information from a debugger might enable someone to find a |
| problem on a machine which he does not have available. However, you |
| need to think when you collect this information if you want it to have |
| any chance of being useful. |
| |
| @cindex backtrace for bug reports |
| For example, many people send just a backtrace, but that is never |
| useful by itself. A simple backtrace with arguments conveys little |
| about GNU Fortran because the compiler is largely data-driven; the same |
| functions are called over and over for different RTL insns, doing |
| different things depending on the details of the insn. |
| |
| Most of the arguments listed in the backtrace are useless because they |
| are pointers to RTL list structure. The numeric values of the |
| pointers, which the debugger prints in the backtrace, have no |
| significance whatever; all that matters is the contents of the objects |
| they point to (and most of the contents are other such pointers). |
| |
| In addition, most compiler passes consist of one or more loops that |
| scan the RTL insn sequence. The most vital piece of information about |
| such a loop---which insn it has reached---is usually in a local variable, |
| not in an argument. |
| |
| @findex debug_rtx |
| What you need to provide in addition to a backtrace are the values of |
| the local variables for several stack frames up. When a local |
| variable or an argument is an RTX, first print its value and then use |
| the GDB command @command{pr} to print the RTL expression that it points |
| to. (If GDB doesn't run on your machine, use your debugger to call |
| the function @code{debug_rtx} with the RTX as an argument.) In |
| general, whenever a variable is a pointer, its value is no use |
| without the data it points to. |
| @end itemize |
| |
| Here are some things that are not necessary: |
| |
| @itemize @bullet |
| @item |
| A description of the envelope of the bug. |
| |
| Often people who encounter a bug spend a lot of time investigating |
| which changes to the input file will make the bug go away and which |
| changes will not affect it. |
| |
| This is often time consuming and not very useful, because the way we |
| will find the bug is by running a single example under the debugger with |
| breakpoints, not by pure deduction from a series of examples. You might |
| as well save your time for something else. |
| |
| Of course, if you can find a simpler example to report @emph{instead} of |
| the original one, that is a convenience. Errors in the output will be |
| easier to spot, running under the debugger will take less time, etc. |
| Most GNU Fortran bugs involve just one function, so the most straightforward |
| way to simplify an example is to delete all the function definitions |
| except the one where the bug occurs. Those earlier in the file may be |
| replaced by external declarations if the crucial function depends on |
| them. (Exception: inline functions might affect compilation of functions |
| defined later in the file.) |
| |
| However, simplification is not vital; if you don't want to do this, |
| report the bug anyway and send the entire test case you used. |
| |
| @item |
| In particular, some people insert conditionals @samp{#ifdef BUG} around |
| a statement which, if removed, makes the bug not happen. These are just |
| clutter; we won't pay any attention to them anyway. Besides, you should |
| send us preprocessor output, and that can't have conditionals. |
| |
| @item |
| A patch for the bug. |
| |
| A patch for the bug is useful if it is a good one. But don't omit the |
| necessary information, such as the test case, on the assumption that a |
| patch is all we need. We might see problems with your patch and decide |
| to fix the problem another way, or we might not understand it at all. |
| |
| Sometimes with a program as complicated as GNU Fortran it is very hard to |
| construct an example that will make the program follow a certain path |
| through the code. If you don't send the example, we won't be able to |
| construct one, so we won't be able to verify that the bug is fixed. |
| |
| And if we can't understand what bug you are trying to fix, or why your |
| patch should be an improvement, we won't install it. A test case will |
| help us to understand. |
| |
| See @uref{http://gcc.gnu.org/contribute.html} |
| for guidelines on how to make it easy for us to |
| understand and install your patches. |
| |
| @item |
| A guess about what the bug is or what it depends on. |
| |
| Such guesses are usually wrong. Even the maintainer can't guess right |
| about such things without first using the debugger to find the facts. |
| |
| @item |
| A core dump file. |
| |
| We have no way of examining a core dump for your type of machine |
| unless we have an identical system---and if we do have one, |
| we should be able to reproduce the crash ourselves. |
| @end itemize |
| |
| @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 |
| GNU CC 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. |
| More relevant information might be available from |
| @uref{ftp://alpha.gnu.org/gnu/g77/projects/}. |
| |
| @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 Index |
| @unnumbered Index |
| |
| @printindex cp |
| @bye |