diff options
Diffstat (limited to 'gcc/f/g77.texi')
| -rw-r--r-- | gcc/f/g77.texi | 13831 |
1 files changed, 13831 insertions, 0 deletions
diff --git a/gcc/f/g77.texi b/gcc/f/g77.texi new file mode 100644 index 00000000000..134deb56ceb --- /dev/null +++ b/gcc/f/g77.texi @@ -0,0 +1,13831 @@ +\input texinfo @c -*-texinfo-*- +@c fix @set inside @example: +@tex +\gdef\set{\begingroup\catcode` =10 \parsearg\setxxx} +\gdef\setyyy#1 #2\endsetyyy{% + \def\temp{#2}% + \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty + \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted. + \fi + \endgroup +} +@end tex + +@c %**start of header +@setfilename g77.info +@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 (For FSF printing, turn on smallbook; that is all that is needed.) + +@c smallbook + +@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 +@setchapternewpage odd + +@ifinfo +This file explains how to use the GNU Fortran system. + +Published by the Free Software Foundation +59 Temple Place - Suite 330 +Boston, MA 02111-1307 USA + +Copyright (C) 1995-1997 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``GNU General Public License,'' ``Funding for Free +Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the sections entitled ``GNU General Public License,'' +``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look +And Feel'@w{}'', and this permission notice, may be included in +translations approved by the Free Software Foundation instead of in the +original English. +@end ifinfo + +Contributed by James Craig Burley (@email{burley@@gnu.ai.mit.edu}). +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}). + +@finalout +@titlepage +@comment The title is printed in a large font. +@center @titlefont{Using GNU Fortran} +@sp 2 +@center James Craig Burley +@sp 3 +@center Last updated 1997-08-11 +@sp 1 +@c The version number appears some more times in this file. + +@center for version 0.5.21 +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1995-1997 Free Software Foundation, Inc. +@sp 2 +For GNU Fortran Version 0.5.21* +@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 make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``GNU General Public License,'' ``Funding for Free +Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the sections entitled ``GNU General Public License,'' +``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look +And Feel'@w{}'', and this permission notice, may be included in +translations approved by the Free Software Foundation instead of in the +original English. +@end titlepage +@page + +@ifinfo + +@dircategory Fortran Programming +@direntry +* g77: (g77). The GNU Fortran compilation system. +@end direntry +@node Top, Copying,, (DIR) +@top Introduction +@cindex Introduction + +@ifset INTERNALS +@ifset USING +This manual documents how to run, install and port the GNU Fortran +compiler, as well as its new features and incompatibilities, and how to +report bugs. It corresponds to GNU Fortran version 0.5.21. +@end ifset +@end ifset + +@ifclear INTERNALS +This manual documents how to run and install the GNU Fortran compiler, +as well as its new features and incompatibilities, and how to report +bugs. It corresponds to GNU Fortran version 0.5.21. +@end ifclear +@ifclear USING +This manual documents how to port the GNU Fortran compiler, +as well as its new features and incompatibilities, and how to report +bugs. It corresponds to GNU Fortran version 0.5.21. +@end ifclear + +@end ifinfo +@menu +* Copying:: GNU General Public License says + how you can copy and share GNU Fortran. +* 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. +* Look and Feel:: Protect your freedom---fight ``look and feel''. +@ifset USING +* Getting Started:: Finding your way around this manual. +* What is GNU Fortran?:: How @code{g77} fits into the universe. +* G77 and GCC:: You can compile Fortran, C, or other programs. +* Invoking G77:: Command options supported by @code{g77}. +* News:: News about recent releases of @code{g77}. +* Changes:: User-visible changes to recent releases of @code{g77}. +* Language:: The GNU Fortran language. +* Compiler:: The GNU Fortran compiler. +* Other Dialects:: Dialects of Fortran supported by @code{g77}. +* Other Compilers:: Fortran compilers other than @code{g77}. +* Other Languages:: Languages other than Fortran. +* Installation:: How to configure, compile and install GNU Fortran. +* Debugging and Interfacing:: How @code{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 @code{g77} about new options. +* Projects:: Projects for @code{g77} internals hackers. +@end ifset + +* M: Diagnostics. Diagnostics produced by @code{g77}. + +* Index:: Index of concepts and symbol names. +@end menu +@c yes, the "M: " @emph{is} intentional -- bad.def references it (CMPAMBIG)! + +@node Copying +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `show c' for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@smallexample +Yoyodyne, Inc., hereby disclaims all copyright interest in the program +`Gnomovision' (which makes passes at compilers) written by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end smallexample + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +@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 GNU CC,gcc,Using and Porting GNU CC}, +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 @code{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 @code{g77}'s +public release. This work consisted of testing, researching, sometimes +debugging, and occasionally providing small amounts of code and fixes +for @code{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 +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, because version 0.6 is still +a ways off. + +@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 @code{g77} code generation to at least be as good +as @code{f2c} used in conjunction with @code{gcc}. +So far, this has resulted in the three, somewhat +experimental, options added by @code{g77} to the @code{gcc} +compiler and its back end. + +@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 @code{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 + +@node Funding +@chapter Funding Free Software + +If you want to have more free software a few years from now, it makes +sense for you to help encourage people to contribute funds for its +development. The most effective approach known is to encourage +commercial redistributors to donate. + +Users of free software systems can boost the pace of development by +encouraging for-a-fee distributors to donate part of their selling price +to free software developers---the Free Software Foundation, and others. + +The way to convince distributors to do this is to demand it and expect +it from them. So when you compare distributors, judge them partly by +how much they give to free software development. Show distributors +they must compete to be the one who gives the most. + +To make this approach work, you must insist on numbers that you can +compare, such as, ``We will donate ten dollars to the Frobnitz project +for each disk sold.'' Don't be satisfied with a vague promise, such as +``A portion of the profits are donated,'' since it doesn't give a basis +for comparison. + +Even a precise fraction ``of the profits from this disk'' is not very +meaningful, since creative accounting and unrelated business decisions +can greatly alter what fraction of the sales price counts as profit. +If the price you pay is $50, ten percent of the profit is probably +less than a dollar; it might be a few cents, or nothing at all. + +Some redistributors do development work themselves. This is useful too; +but to keep everyone honest, you need to inquire how much they do, and +what kind. Some kinds of development make much more long-term +difference than others. For example, maintaining a separate version of +a program contributes very little; maintaining the standard version of a +program for the whole community contributes much. Easy new ports +contribute little, since someone else would surely do them; difficult +ports such as adding a new CPU to the GNU C compiler contribute more; +major new features or packages contribute the most. + +By establishing the idea that supporting further development is ``the +proper thing to do'' when distributing free software for a fee, we can +assure a steady flow of resources into making more free software. + +@display +Copyright (C) 1994 Free Software Foundation, Inc. +Verbatim copying and redistribution of this section is permitted +without royalty; alteration is not permitted. +@end display + +@node Funding GNU Fortran +@chapter Funding GNU Fortran +@cindex funding improvements +@cindex improvements, funding + +Work on GNU Fortran is still being done mostly by its author, +James Craig Burley (@email{burley@@gnu.ai.mit.edu}), who is a volunteer +for, not an employee of, the Free Software Foundation (FSF). +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@@prep.ai.mit.edu} for information on funding the FSF. + +To fund specific GNU Fortran work in particular, the FSF might +provide a means for that, but the FSF does not provide direct funding +to the author of GNU Fortran to continue his work. The FSF has +employee salary restrictions that can be incompatible with the +financial needs of some volunteers, who therefore choose to +remain volunteers and thus be able to be free to do contract work +and otherwise make their own schedules for doing GNU work. + +Still, funding the FSF at least indirectly benefits work +on specific projects like GNU Fortran because it ensures the +continuing operation of the FSF offices, their workstations, their +network connections, and so on, which are invaluable to volunteers. +(Similarly, hiring Cygnus Support can help a project like GNU +Fortran---Cygnus has been a long-time donor of equipment usage to the author +of GNU Fortran, and this too has been invaluable---@xref{Contributors}.) + +Currently, the only way to directly fund the author of GNU Fortran +in his work on that project is to hire him for the work you want +him to do, or donate money to him. +Several people have done this +already, with the result that he has not needed to immediately find +contract work on a few occasions. +If more people did this, he +would be able to plan on not doing contract work for many months and +could thus devote that time to work on projects (such as the planned +changes for 0.6) that require longer timeframes to complete. +For the latest information on the status of the author, do +@kbd{finger -l burley@@gate.gnu.ai.mit.edu} on a UNIX system +(or any system with a command like UNIX @code{finger}). + +Another important way to support work on GNU Fortran is to volunteer +to help out. +Work is needed on documentation, testing, porting +to various machines, and in some cases, coding (although major +changes planned for version 0.6 make it difficult to add manpower to this +area). +Email @email{fortran@@gnu.ai.mit.edu} to volunteer for this work. + +@xref{Funding,,Funding Free Software}, for more information. + +@node Look and Feel +@chapter Protect Your Freedom---Fight ``Look And Feel'' +@c the above chapter heading overflows onto the next line. --mew 1/26/93 + +To preserve the ability to write free software, including replacements +for proprietary software, authors must be free to replicate the +user interface to which users of existing software have become +accustomed. + +@xref{Look and Feel,,Protect Your Freedom---Fight ``Look And Feel'', +gcc,Using and Porting GNU CC}, 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 @code{gcc}, +you should see @ref{G77 and GCC}. + +Everyone except experienced @code{g77} users should +see @ref{Invoking G77}. + +If you're acquainted with previous versions of @code{g77}, +you should see @ref{News}. +Further, if you've actually used previous versions of @code{g77}, +especially if you've written or modified Fortran code to +be compiled by previous versions of @code{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 don't already have @code{g77} installed on your +system, you must see @ref{Installation}. + +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 @code{g77}---see @ref{Bugs}, for information on +reporting them, after reading the other material. + +If you need further help with @code{g77}, or with +freely redistributable software in general, +see @ref{Service}. + +If you would like to help the @code{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 +@code{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 @code{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 @code{g77}, is designed initially as a free replacement +for, or alternative to, the UNIX @code{f77} command. +(Similarly, @code{gcc} is designed as a replacement +for the UNIX @code{cc} command.) + +@code{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, @code{g77}, @code{gcc}, and @code{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 gdb command +@cindex commands, 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 @code{gdb}). + +@cindex libraries +@cindex linking +@cindex ld command +@cindex commands, 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 +@code{ld} command. +However, the @code{g77} and @code{gcc} +commands, as with most compiler commands, automatically +perform the linking step by calling on @code{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 g77 +@cindex g77, components of +@code{g77} consists of several components: + +@cindex gcc command +@cindex commands, gcc +@itemize @bullet +@item +A modified version of the @code{gcc} command, which also might be +installed as the system's @code{cc} command. +(In many cases, @code{cc} refers to the +system's ``native'' C compiler, which +might be a non-GNU compiler, or an older version +of @code{gcc} considered more stable or that is +used to build the operating system kernel.) + +@cindex g77 command +@cindex commands, g77 +@item +The @code{g77} command itself, which also might be installed as the +system's @code{f77} command. + +@cindex libf2c library +@cindex libraries, libf2c +@cindex run-time library +@item +The @code{libf2c} 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 @code{g77} +compilation phase. + +@cindex f771 program +@cindex programs, f771 +@cindex assembler +@cindex as command +@cindex commands, 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 @code{as}. +@end itemize + +@code{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, @code{gcc} determines which actions to perform, including +preprocessing, compiling (in a variety of possible languages), assembling, +and linking. + +@cindex driver, gcc command as +@cindex 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 @code{cpp}, then +the C compiler (internally named +@code{cc1}), then the assembler (usually @code{as}), then the linker +(@code{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}, +@code{gcc} would use the C++ compiler (named @code{cc1plus}). + +@cindex f771 program +@cindex programs, f771 +In a GNU Fortran installation, @code{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 gcc not recognizing Fortran source +@cindex unrecognized file format +@cindex file format not recognized +Non-Fortran-related operation of @code{gcc} is generally +unaffected by installing the GNU Fortran version of @code{gcc}. +However, without the installed version of @code{gcc} being the +GNU Fortran version, @code{gcc} will not be able to compile +and link Fortran programs---and since @code{g77} uses @code{gcc} +to do most of the actual work, neither will @code{g77}! + +@cindex g77 command +@cindex commands, g77 +The @code{g77} command is essentially just a front-end for +the @code{gcc} command. +Fortran users will normally use @code{g77} instead of @code{gcc}, +because @code{g77} +knows how to specify the libraries needed to link with Fortran programs +(@code{libf2c} and @code{lm}). +@code{g77} can still compile and link programs and +source files written in other languages, just like @code{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 @code{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 @code{gcc} +with which that version of @code{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 @code{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 @code{g77} when compiling Fortran code) into machine +code that, when run, calls on functions in @code{libf2c}, so +@code{libf2c} must be linked with almost every useful program +having any component compiled by GNU Fortran. +(As mentioned above, the @code{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{libf2c} component is really part of @code{f2c}, +a free Fortran-to-C converter distributed by Bellcore (AT&T), +plus @code{libU77}, provided by Dave Love, +and the @code{g77} command is just a small front-end to @code{gcc}, +@code{f771} is a combination of two rather +large chunks of code. + +@cindex GNU Back End (GBE) +@cindex GBE +@cindex 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 g77 front end +@cindex front end, 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 @samp{-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 gcc command +@cindex commands, gcc +A GNU Fortran installation includes a modified version of the @code{gcc} +command. + +In a non-Fortran installation, @code{gcc} recognizes C, C++, +and Objective-C source files. + +In a GNU Fortran installation, @code{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++; or Objective-C,gcc,Using and Porting GNU CC}, +for information on the way different languages are handled +by the GNU CC compiler (@code{gcc}). + +@cindex g77 command +@cindex commands, g77 +Also provided as part of GNU Fortran is the @code{g77} command. +The @code{g77} command is designed to make compiling and linking Fortran +programs somewhat easier than when using the @code{gcc} command for +these tasks. +It does this by analyzing the command line somewhat and changing it +appropriately before submitting it to the @code{gcc} command. + +@cindex -v option +@cindex g77 options, -v +@cindex options, -v +@cindex -@w{}-driver option +@cindex g77 options, -@w{}-driver +@cindex options, -@w{}-driver +Use the @samp{-v} option with @code{g77} +to see what is going on---the first line of output is the invocation +of the @code{gcc} command. +Use @samp{--driver=true} to disable actual invocation +of @code{gcc} (this works because @samp{true} is the name of a +UNIX command that simply returns success status). + +@node Invoking G77 +@chapter GNU Fortran Command Options +@cindex GNU Fortran command options +@cindex command options +@cindex options, GNU Fortran command + +The @code{g77} command supports all the options supported by the +@code{gcc} command. +@xref{Invoking GCC,,GNU CC Command Options,gcc,Using and Porting GNU CC}, +for information +on the non-Fortran-specific aspects of the @code{gcc} command (and, +therefore, the @code{g77} command). + +The @code{g77} command supports one option not supported by +the @code{gcc} command: + +@table @code +@cindex -@w{}-driver option +@cindex g77 options, -@w{}-driver +@cindex options, -@w{}-driver +@item --driver=@var{command} +Specifies that @var{command}, rather than @code{gcc}, is to +be invoked by @code{g77} to do its job. +For example, within the @code{gcc} build directory after +building GNU Fortran (but without having to install it), +@kbd{./g77 --driver=./xgcc foo.f -B./}. +@end table + +@cindex options, negative forms +@cindex negative forms of options +All other options are supported both by @code{g77} and by @code{gcc} as +modified (and reinstalled) by the @code{g77} distribution. +In some cases, options have positive and negative forms; +the negative form of @samp{-ffoo} would be @samp{-fno-foo}. +This manual documents only one of these two forms, whichever +one is not the default. + +@menu +* Option Summary:: Brief list of all @code{g77} options, + without explanations. +* Overall Options:: Controlling the kind of output: + an executable, object files, assembler files, + or preprocessed source. +* Shorthand Options:: Options that are shorthand for other options. +* Fortran Dialect Options:: Controlling the variant of Fortran language + compiled. +* Warning Options:: How picky should the compiler be? +* Debugging Options:: Symbol tables, measurements, and debugging dumps. +* Optimize Options:: How much optimization? +* Preprocessor Options:: Controlling header files and macro definitions. + Also, getting dependency information for Make. +* Directory Options:: Where to find header files and libraries. + Where to find the compiler executable files. +* Code Gen Options:: Specifying conventions for function calls, data layout + and register usage. +* Environment Variables:: Env vars that affect GNU Fortran. +@end menu + +@node Option Summary +@section Option Summary + +Here is a summary of all the options specific to GNU Fortran, grouped +by type. Explanations are in the following sections. + +@table @emph +@item Overall Options +@xref{Overall Options,,Options Controlling the Kind of Output}. +@smallexample +--driver -fversion -fset-g77-defaults -fno-silent +@end smallexample + +@item Shorthand Options +@xref{Shorthand Options}. +@smallexample +-ff66 -fno-f66 -ff77 -fno-f77 -fugly -fno-ugly +@end smallexample + +@item Fortran Language Options +@xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}. +@smallexample +-ffree-form -fno-fixed-form -ff90 +-fvxt -fdollar-ok -fno-backslash +-fno-ugly-args -fno-ugly-assign -fno-ugly-assumed +-fugly-comma -fugly-complex -fugly-init -fugly-logint +-fonetrip -ftypeless-boz +-fintrin-case-initcap -fintrin-case-upper +-fintrin-case-lower -fintrin-case-any +-fmatch-case-initcap -fmatch-case-upper +-fmatch-case-lower -fmatch-case-any +-fsource-case-upper -fsource-case-lower -fsource-case-preserve +-fsymbol-case-initcap -fsymbol-case-upper +-fsymbol-case-lower -fsymbol-case-any +-fcase-strict-upper -fcase-strict-lower +-fcase-initcap -fcase-upper -fcase-lower -fcase-preserve +-ff2c-intrinsics-delete -ff2c-intrinsics-hide +-ff2c-intrinsics-disable -ff2c-intrinsics-enable +-ff90-intrinsics-delete -ff90-intrinsics-hide +-ff90-intrinsics-disable -ff90-intrinsics-enable +-fgnu-intrinsics-delete -fgnu-intrinsics-hide +-fgnu-intrinsics-disable -fgnu-intrinsics-enable +-fmil-intrinsics-delete -fmil-intrinsics-hide +-fmil-intrinsics-disable -fmil-intrinsics-enable +-funix-intrinsics-delete -funix-intrinsics-hide +-funix-intrinsics-disable -funix-intrinsics-enable +-fvxt-intrinsics-delete -fvxt-intrinsics-hide +-fvxt-intrinsics-disable -fvxt-intrinsics-enable +-ffixed-line-length-@var{n} -ffixed-line-length-none +@end smallexample + +@item Warning Options +@xref{Warning Options,,Options to Request or Suppress Warnings}. +@smallexample +-fsyntax-only -pedantic -pedantic-errors -fpedantic +-w -Wno-globals -Wimplicit -Wunused -Wuninitialized +-Wall -Wsurprising +-Werror -W +@end smallexample + +@item Debugging Options +@xref{Debugging Options,,Options for Debugging Your Program or GCC}. +@smallexample +-g +@end smallexample + +@item Optimization Options +@xref{Optimize Options,,Options that Control Optimization}. +@smallexample +-malign-double +-ffloat-store -fforce-mem -fforce-addr -fno-inline +-ffast-math -fstrength-reduce -frerun-cse-after-loop +-fexpensive-optimizations -fdelayed-branch +-fschedule-insns -fschedule-insn2 -fcaller-saves +-funroll-loops -funroll-all-loops +-fno-move-all-movables -fno-reduce-all-givs +-fno-rerun-loop-opt +@end smallexample + +@item Directory Options +@xref{Directory Options,,Options for Directory Search}. +@smallexample +-I@var{dir} -I- +@end smallexample + +@item Code Generation Options +@xref{Code Gen Options,,Options for Code Generation Conventions}. +@smallexample +-fno-automatic -finit-local-zero -fno-f2c +-ff2c-library -fno-underscoring -fno-ident +-fpcc-struct-return -freg-struct-return +-fshort-double -fno-common -fpack-struct +-fzeros -fno-second-underscore +-fdebug-kludge -fno-emulate-complex +-falias-check -fargument-alias +-fargument-noalias -fno-argument-noalias-global +-fno-globals +@end smallexample +@end table + +@menu +* Overall Options:: Controlling the kind of output: + an executable, object files, assembler files, + or preprocessed source. +* Shorthand Options:: Options that are shorthand for other options. +* Fortran Dialect Options:: Controlling the variant of Fortran language + compiled. +* Warning Options:: How picky should the compiler be? +* Debugging Options:: Symbol tables, measurements, and debugging dumps. +* Optimize Options:: How much optimization? +* Preprocessor Options:: Controlling header files and macro definitions. + Also, getting dependency information for Make. +* Directory Options:: Where to find header files and libraries. + Where to find the compiler executable files. +* Code Gen Options:: Specifying conventions for function calls, data layout + and register usage. +@end menu + +@node Overall Options +@section Options Controlling the Kind of Output +@cindex overall options +@cindex options, overall + +Compilation can involve as many as four stages: preprocessing, code +generation (often what is really meant by the term ``compilation''), +assembly, and linking, always in that order. The first three +stages apply to an individual source file, and end by producing an +object file; linking combines all the object files (those newly +compiled, and those specified as input) into an executable file. + +@cindex file name suffix +@cindex suffixes, file name +@cindex file name extension +@cindex extensions, file name +@cindex file type +@cindex types, file +For any given input file, the file name suffix determines what kind of +program is contained in the file---that is, the language in which the +program is written is generally indicated by the suffix. +Suffixes specific to GNU Fortran are listed below. +@xref{Overall Options,,gcc,Using and Porting GNU CC}, for +information on suffixes recognized by GNU CC. + +@table @code +@item @var{file}.f +@item @var{file}.for +Fortran source code that should not be preprocessed. + +Such source code cannot contain any preprocessor directives, such +as @code{#include}, @code{#define}, @code{#if}, and so on. + +@cindex preprocessor +@cindex C preprocessor +@cindex cpp preprocessor +@cindex Fortran preprocessor +@cindex cpp program +@cindex programs, cpp +@cindex .F filename suffix +@cindex .fpp filename suffix +@item @var{file}.F +@item @var{file}.fpp +Fortran source code that must be preprocessed (by the C preprocessor +@code{cpp}, which is part of GNU CC). + +Note that preprocessing is not extended to the contents of +files included by the @code{INCLUDE} directive---the @code{#include} +preprocessor directive must be used instead. + +@cindex Ratfor preprocessor +@cindex programs, ratfor +@cindex .r filename suffix +@item @var{file}.r +Ratfor source code, which must be preprocessed by the @code{ratfor} +command, which is available separately (as it is not yet part of +the GNU Fortran distribution). +@end table + +UNIX users typically use the @file{@var{file}.f} and @file{@var{file}.F} +nomenclature. +Users of other operating systems, especially those that cannot +distinguish upper-case +letters from lower-case letters in their file names, typically use +the @file{@var{file}.for} and @file{@var{file}.fpp} nomenclature. + +@cindex #define +@cindex #include +@cindex #if +Use of the preprocessor @code{cpp} allows use of C-like +constructs such as @code{#define} and @code{#include}, but can +lead to unexpected, even mistaken, results due to Fortran's source file +format. +It is recommended that use of the C preprocessor +be limited to @code{#include} and, in +conjunction with @code{#define}, only @code{#if} and related directives, +thus avoiding in-line macro expansion entirely. +This recommendation applies especially +when using the traditional fixed source form. +With free source form, +fewer unexpected transformations are likely to happen, but use of +constructs such as Hollerith and character constants can nevertheless +present problems, especially when these are continued across multiple +source lines. +These problems result, primarily, from differences between the way +such constants are interpreted by the C preprocessor and by a Fortran +compiler. + +@emph{Note:} The @samp{-traditional} and @samp{-undef} flags are supplied +to @code{cpp} by default, to avoid unpleasant surprises. +@xref{Preprocessor Options,,Options Controlling the Preprocessor, +gcc,Using and Porting GNU CC}. +This means that ANSI C preprocessor features (such as the @samp{#} +operator) aren't available, and only variables in the C reserved +namespace (generally, names with a leading underscore) are liable to +substitution by C predefines. +Thus, if you want to do system-specific +tests, use, for example, @samp{#ifdef __linux__} rather than @samp{#ifdef linux}. +Use the @samp{-v} option to see exactly how the preprocessor is invoked. + +The following options that affect overall processing are recognized +by the @code{g77} and @code{gcc} commands in a GNU Fortran installation: + +@table @code +@item --driver=@var{command} +This works when invoking only the @code{g77} command, not +when invoking the @code{gcc} command. +@xref{Invoking G77,,GNU Fortran Command Options}, for +information on this option. + +@cindex -fversion option +@cindex options, -fversion +@cindex printing version information +@cindex version information, printing +@item -fversion +Ensure that the @code{g77}-specific version of the compiler phase is reported, +if run. +(This is supplied automatically when @samp{-v} or @samp{--verbose} +is specified as a command-line option for @code{g77} or @code{gcc} +and when the resulting commands compile Fortran source files.) + +@cindex -fset-g77-defaults option +@cindex options, -fset-g77-defaults +@item -fset-g77-defaults +Set up whatever @code{gcc} options are to apply to Fortran +compilations, and avoid running internal consistency checks +that might take some time. + +As of version 0.5.20, this is equivalent to @samp{-fmove-all-movables +-freduce-all-givs -frerun-loop-opt -fargument-noalias-global}. + +This option is supplied automatically when compiling Fortran code +via the @code{g77} or @code{gcc} command. +The description of this option is provided so that users seeing +it in the output of, say, @samp{g77 -v} understand why it is +there. + +@cindex modifying g77 +@cindex code, modifying +Also, developers who run @code{f771} directly might want to specify it +by hand to get the same defaults as they would running @code{f771} +via @code{g77} or @code{gcc}. +However, such developers should, after linking a new @code{f771} +executable, invoke it without this option once, +e.g. via @kbd{./f771 -quiet < /dev/null}, +to ensure that they have not introduced any +internal inconsistencies (such as in the table of +intrinsics) before proceeding---@code{g77} will crash +with a diagnostic if it detects an inconsistency. + +@cindex -fno-silent option +@cindex options, -fno-silent +@cindex @code{f2c} compatibility +@cindex compatibility, @code{f2c} +@cindex status, compilation +@cindex compilation status +@cindex reporting compilation status +@cindex printing compilation status +@item -fno-silent +Print (to @code{stderr}) the names of the program units as +they are compiled, in a form similar to that used by popular +UNIX @code{f77} implementations and @code{f2c}. +@end table + +@xref{Overall Options,,Options Controlling the Kind of Output, +gcc,Using and Porting GNU CC}, for information +on more options that control the overall operation of the @code{gcc} command +(and, by extension, the @code{g77} command). + +@node Shorthand Options +@section Shorthand Options +@cindex shorthand options +@cindex options, shorthand +@cindex macro options +@cindex options, macro + +The following options serve as ``shorthand'' +for other options accepted by the compiler: + +@table @code +@cindex -fugly option +@cindex options, -fugly +@item -fugly +@cindex ugly features +@cindex features, ugly +Specify that certain ``ugly'' constructs are to be quietly accepted. +Same as: + +@smallexample +-fugly-args -fugly-assign -fugly-assumed +-fugly-comma -fugly-complex -fugly-init +-fugly-logint +@end smallexample + +These constructs are considered inappropriate to use in new +or well-maintained portable Fortran code, but widely used +in old code. +@xref{Distensions}, for more information. + +@emph{Note:} The @samp{-fugly} option is likely to +be removed in a future version. +Implicitly enabling all the @samp{-fugly-*} options +is unlikely to be feasible, or sensible, in the future, +so users should learn to specify only those +@samp{-fugly-*} options they really need for a +particular source file. + +@cindex -fno-ugly option +@cindex options, -fno-ugly +@item -fno-ugly +@cindex ugly features +@cindex features, ugly +Specify that all ``ugly'' constructs are to be noisily rejected. +Same as: + +@smallexample +-fno-ugly-args -fno-ugly-assign -fno-ugly-assumed +-fno-ugly-comma -fno-ugly-complex -fno-ugly-init +-fno-ugly-logint +@end smallexample + +@xref{Distensions}, for more information. + +@cindex -ff66 option +@cindex options, -ff66 +@item -ff66 +@cindex FORTRAN 66 +@cindex compatibility, FORTRAN 66 +Specify that the program is written in idiomatic FORTRAN 66. +Same as @samp{-fonetrip -fugly-assumed}. + +The @samp{-fno-f66} option is the inverse of @samp{-ff66}. +As such, it is the same as @samp{-fno-onetrip -fno-ugly-assumed}. + +The meaning of this option is likely to be refined as future +versions of @code{g77} provide more compatibility with other +existing and obsolete Fortran implementations. + +@cindex -ff77 option +@cindex options, -ff77 +@item -ff77 +@cindex UNIX f77 +@cindex @code{f2c} compatibility +@cindex compatibility, @code{f2c} +@cindex @code{f77} compatibility +@cindex compatibility, @code{f77} +Specify that the program is written in idiomatic UNIX FORTRAN 77 +and/or the dialect accepted by the @code{f2c} product. +Same as @samp{-fbackslash -fno-typeless-boz}. + +The meaning of this option is likely to be refined as future +versions of @code{g77} provide more compatibility with other +existing and obsolete Fortran implementations. + +@cindex -fno-f77 option +@cindex options, -fno-f77 +@item -fno-f77 +@cindex UNIX f77 +The @samp{-fno-f77} option is @emph{not} the inverse +of @samp{-ff77}. +It specifies that the program is not written in idiomatic UNIX +FORTRAN 77 or @code{f2c}, but in a more widely portable dialect. +@samp{-fno-f77} is the same as @samp{-fno-backslash}. + +The meaning of this option is likely to be refined as future +versions of @code{g77} provide more compatibility with other +existing and obsolete Fortran implementations. +@end table + +@node Fortran Dialect Options +@section Options Controlling Fortran Dialect +@cindex dialect options +@cindex language dialect options +@cindex options, dialect + +The following options control the dialect of Fortran +that the compiler accepts: + +@table @code +@cindex -ffree-form option +@cindex options, -ffree-form +@cindex -fno-fixed-form option +@cindex options, -fno-fixed-form +@cindex source file form +@cindex free form +@cindex fixed form +@cindex Fortran 90 features +@item -ffree-form +@item -fno-fixed-form +Specify that the source file is written in free form +(introduced in Fortran 90) instead of the more-traditional fixed form. + +@cindex -ff90 option +@cindex options, -ff90 +@cindex Fortran 90 features +@item -ff90 +Allow certain Fortran-90 constructs. + +This option controls whether certain +Fortran 90 constructs are recognized. +(Other Fortran 90 constructs +might or might not be recognized depending on other options such as +@samp{-fvxt}, @samp{-ff90-intrinsics-enable}, and the +current level of support for Fortran 90.) + +@xref{Fortran 90}, for more information. + +@cindex -fvxt option +@cindex options, -fvxt +@item -fvxt +@cindex Fortran 90 features +@cindex VXT features +Specify the treatment of certain constructs that have different +meanings depending on whether the code is written in +GNU Fortran (based on FORTRAN 77 and akin to Fortran 90) +or VXT Fortran (more like VAX FORTRAN). + +The default is @samp{-fno-vxt}. +@samp{-fvxt} specifies that the VXT Fortran interpretations +for those constructs are to be chosen. + +@xref{VXT Fortran}, for more information. + +@cindex -fdollar-ok option +@cindex options, -fdollar-ok +@item -fdollar-ok +@cindex dollar sign +@cindex symbol names +@cindex character set +Allow @samp{$} as a valid character in a symbol name. + +@cindex -fno-backslash option +@cindex options, -fno-backslash +@item -fno-backslash +@cindex backslash +@cindex character constants +@cindex Hollerith constants +Specify that @samp{\} is not to be specially interpreted in character +and Hollerith constants a la C and many UNIX Fortran compilers. + +For example, with @samp{-fbackslash} in effect, @samp{A\nB} specifies +three characters, with the second one being newline. +With @samp{-fno-backslash}, it specifies four characters, +@samp{A}, @samp{\}, @samp{n}, and @samp{B}. + +Note that @code{g77} implements a fairly general form of backslash +processing that is incompatible with the narrower forms supported +by some other compilers. +For example, @samp{'A\003B'} is a three-character string in @code{g77}, +whereas other compilers that support backslash might not support +the three-octal-digit form, and thus treat that string as longer +than three characters. + +@xref{Backslash in Constants}, for +information on why @samp{-fbackslash} is the default +instead of @samp{-fno-backslash}. + +@cindex -fno-ugly-args option +@cindex options, -fno-ugly-args +@item -fno-ugly-args +Disallow passing Hollerith and typeless constants as actual +arguments (for example, @samp{CALL FOO(4HABCD)}). + +@xref{Ugly Implicit Argument Conversion}, for more information. + +@cindex -fugly-assign option +@cindex options, -fugly-assign +@item -fugly-assign +Use the same storage for a given variable regardless of +whether it is used to hold an assigned-statement label +(as in @samp{ASSIGN 10 TO I}) or used to hold numeric data +(as in @samp{I = 3}). + +@xref{Ugly Assigned Labels}, for more information. + +@cindex -fugly-assumed option +@cindex options, -fugly-assumed +@item -fugly-assumed +Assume any dummy array with a final dimension specified as @samp{1} +is really an assumed-size array, as if @samp{*} had been specified +for the final dimension instead of @samp{1}. + +For example, @samp{DIMENSION X(1)} is treated as if it +had read @samp{DIMENSION X(*)}. + +@xref{Ugly Assumed-Size Arrays}, for more information. + +@cindex -fugly-comma option +@cindex options, -fugly-comma +@item -fugly-comma +Treat a trailing comma in an argument list as specification +of a trailing null argument, and treat an empty argument +list as specification of a single null argument. + +For example, @samp{CALL FOO(,)} is treated as +@samp{CALL FOO(%VAL(0), %VAL(0))}. +That is, @emph{two} null arguments are specified +by the procedure call when @samp{-fugly-comma} is in force. +And @samp{F = FUNC()} is treated as @samp{F = FUNC(%VAL(0))}. + +The default behavior, @samp{-fno-ugly-comma}, is to ignore +a single trailing comma in an argument list. + +@xref{Ugly Null Arguments}, for more information. + +@cindex -fugly-complex option +@cindex options, -fugly-complex +@item -fugly-complex +Do not complain about @samp{REAL(@var{expr})} or +@samp{AIMAG(@var{expr})} when @var{expr} is a @code{COMPLEX} +type other than @code{COMPLEX(KIND=1)}---usually +this is used to permit @code{COMPLEX(KIND=2)} +(@code{DOUBLE COMPLEX}) operands. + +The @samp{-ff90} option controls the interpretation +of this construct. + +@xref{Ugly Complex Part Extraction}, for more information. + +@cindex -fno-ugly-init option +@cindex options, -fno-ugly-init +@item -fno-ugly-init +Disallow use of Hollerith and typeless constants as initial +values (in @code{PARAMETER} and @code{DATA} statements), and +use of character constants to +initialize numeric types and vice versa. + +For example, @samp{DATA I/'F'/, CHRVAR/65/, J/4HABCD/} is disallowed by +@samp{-fno-ugly-init}. + +@xref{Ugly Conversion of Initializers}, for more information. + +@cindex -fugly-logint option +@cindex options, -fugly-logint +@item -fugly-logint +Treat @code{INTEGER} and @code{LOGICAL} variables and +expressions as potential stand-ins for each other. + +For example, automatic conversion between @code{INTEGER} and +@code{LOGICAL} is enabled, for many contexts, via this option. + +@xref{Ugly Integer Conversions}, for more information. + +@cindex -fonetrip option +@cindex options, -fonetrip +@item -fonetrip +@cindex FORTRAN 66 +@cindex DO loops, one-trip +@cindex one-trip DO loops +@cindex compatibility, FORTRAN 66 +Imperative executable @code{DO} loops are to be executed at +least once each time they are reached. + +ANSI FORTRAN 77 and more recent versions of the Fortran standard +specify that the body of an imperative @code{DO} loop is not executed +if the number of iterations calculated from the parameters of the +loop is less than 1. +(For example, @samp{DO 10 I = 1, 0}.)@ +Such a loop is called a @dfn{zero-trip loop}. + +Prior to ANSI FORTRAN 77, many compilers implemented @code{DO} loops +such that the body of a loop would be executed at least once, even +if the iteration count was zero. +Fortran code written assuming this behavior is said to require +@dfn{one-trip loops}. +For example, some code written to the FORTRAN 66 standard +expects this behavior from its @code{DO} loops, although that +standard did not specify this behavior. + +The @samp{-fonetrip} option specifies that the source file(s) being +compiled require one-trip loops. + +This option affects only those loops specified by the (imperative) @code{DO} +statement and by implied-@code{DO} lists in I/O statements. +Loops specified by implied-@code{DO} lists in @code{DATA} and +specification (non-executable) statements are not affected. + +@cindex -ftypeless-boz option +@cindex options, -ftypeless-boz +@cindex prefix-radix constants +@cindex constants, prefix-radix +@cindex constants, types +@cindex types, constants +@item -ftypeless-boz +Specifies that prefix-radix non-decimal constants, such as +@samp{Z'ABCD'}, are typeless instead of @code{INTEGER(KIND=1)}. + +You can test for yourself whether a particular compiler treats +the prefix form as @code{INTEGER(KIND=1)} or typeless by running the +following program: + +@smallexample +EQUIVALENCE (I, R) +R = Z'ABCD1234' +J = Z'ABCD1234' +IF (J .EQ. I) PRINT *, 'Prefix form is TYPELESS' +IF (J .NE. I) PRINT *, 'Prefix form is INTEGER' +END +@end smallexample + +Reports indicate that many compilers process this form as +@code{INTEGER(KIND=1)}, though a few as typeless, and at least one +based on a command-line option specifying some kind of +compatibility. + +@cindex -fintrin-case-initcap option +@cindex options, -fintrin-case-initcap +@item -fintrin-case-initcap +@cindex -fintrin-case-upper option +@cindex options, -fintrin-case-upper +@item -fintrin-case-upper +@cindex -fintrin-case-lower option +@cindex options, -fintrin-case-lower +@item -fintrin-case-lower +@cindex -fintrin-case-any option +@cindex options, -fintrin-case-any +@item -fintrin-case-any +Specify expected case for intrinsic names. +@samp{-fintrin-case-lower} is the default. + +@cindex -fmatch-case-initcap option +@cindex options, -fmatch-case-initcap +@item -fmatch-case-initcap +@cindex -fmatch-case-upper option +@cindex options, -fmatch-case-upper +@item -fmatch-case-upper +@cindex -fmatch-case-lower option +@cindex options, -fmatch-case-lower +@item -fmatch-case-lower +@cindex -fmatch-case-any option +@cindex options, -fmatch-case-any +@item -fmatch-case-any +Specify expected case for keywords. +@samp{-fmatch-case-lower} is the default. + +@cindex -fsource-case-upper option +@cindex options, -fsource-case-upper +@item -fsource-case-upper +@cindex -fsource-case-lower option +@cindex options, -fsource-case-lower +@item -fsource-case-lower +@cindex -fsource-case-preserve option +@cindex options, -fsource-case-preserve +@item -fsource-case-preserve +Specify whether source text other than character and Hollerith constants +is to be translated to uppercase, to lowercase, or preserved as is. +@samp{-fsource-case-lower} is the default. + +@cindex -fsymbol-case-initcap option +@cindex options, -fsymbol-case-initcap +@item -fsymbol-case-initcap +@cindex -fsymbol-case-upper option +@cindex options, -fsymbol-case-upper +@item -fsymbol-case-upper +@cindex -fsymbol-case-lower option +@cindex options, -fsymbol-case-lower +@item -fsymbol-case-lower +@cindex -fsymbol-case-any option +@cindex options, -fsymbol-case-any +@item -fsymbol-case-any +Specify valid cases for user-defined symbol names. +@samp{-fsymbol-case-any} is the default. + +@cindex -fcase-strict-upper option +@cindex options, -fcase-strict-upper +@item -fcase-strict-upper +Same as @samp{-fintrin-case-upper -fmatch-case-upper -fsource-case-preserve +-fsymbol-case-upper}. +(Requires all pertinent source to be in uppercase.) + +@cindex -fcase-strict-lower option +@cindex options, -fcase-strict-lower +@item -fcase-strict-lower +Same as @samp{-fintrin-case-lower -fmatch-case-lower -fsource-case-preserve +-fsymbol-case-lower}. +(Requires all pertinent source to be in lowercase.) + +@cindex -fcase-initcap option +@cindex options, -fcase-initcap +@item -fcase-initcap +Same as @samp{-fintrin-case-initcap -fmatch-case-initcap -fsource-case-preserve +-fsymbol-case-initcap}. +(Requires all pertinent source to be in initial capitals, +as in @samp{Print *,SqRt(Value)}.) + +@cindex -fcase-upper option +@cindex options, -fcase-upper +@item -fcase-upper +Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-upper +-fsymbol-case-any}. +(Maps all pertinent source to uppercase.) + +@cindex -fcase-lower option +@cindex options, -fcase-lower +@item -fcase-lower +Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-lower +-fsymbol-case-any}. +(Maps all pertinent source to lowercase.) + +@cindex -fcase-preserve option +@cindex options, -fcase-preserve +@item -fcase-preserve +Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-preserve +-fsymbol-case-any}. +(Preserves all case in user-defined symbols, +while allowing any-case matching of intrinsics and keywords. +For example, @samp{call Foo(i,I)} would pass two @emph{different} +variables named @samp{i} and @samp{I} to a procedure named @samp{Foo}.) + +@cindex -ff2c-intrinsics-delete option +@cindex options, -ff2c-intrinsics-delete +@item -ff2c-intrinsics-delete +@cindex -ff2c-intrinsics-hide option +@cindex options, -ff2c-intrinsics-hide +@item -ff2c-intrinsics-hide +@cindex -ff2c-intrinsics-disable option +@cindex options, -ff2c-intrinsics-disable +@item -ff2c-intrinsics-disable +@cindex -ff2c-intrinsics-enable option +@cindex options, -ff2c-intrinsics-enable +@item -ff2c-intrinsics-enable +@cindex f2c intrinsics +@cindex intrinsics, f2c +Specify status of f2c-specific intrinsics. +@samp{-ff2c-intrinsics-enable} is the default. + +@cindex -ff90-intrinsics-delete option +@cindex options, -ff90-intrinsics-delete +@item -ff90-intrinsics-delete +@cindex -ff90-intrinsics-hide option +@cindex options, -ff90-intrinsics-hide +@item -ff90-intrinsics-hide +@cindex -ff90-intrinsics-disable option +@cindex options, -ff90-intrinsics-disable +@item -ff90-intrinsics-disable +@cindex -ff90-intrinsics-enable option +@cindex options, -ff90-intrinsics-enable +@item -ff90-intrinsics-enable +@cindex Fortran 90 intrinsics +@cindex intrinsics, Fortran 90 +Specify status of F90-specific intrinsics. +@samp{-ff90-intrinsics-enable} is the default. + +@cindex -fgnu-intrinsics-delete option +@cindex options, -fgnu-intrinsics-delete +@item -fgnu-intrinsics-delete +@cindex -fgnu-intrinsics-hide option +@cindex options, -fgnu-intrinsics-hide +@item -fgnu-intrinsics-hide +@cindex -fgnu-intrinsics-disable option +@cindex options, -fgnu-intrinsics-disable +@item -fgnu-intrinsics-disable +@cindex -fgnu-intrinsics-enable option +@cindex options, -fgnu-intrinsics-enable +@item -fgnu-intrinsics-enable +@cindex Digital Fortran features +@cindex COMPLEX intrinsics +@cindex intrinsics, COMPLEX +Specify status of Digital's COMPLEX-related intrinsics. +@samp{-fgnu-intrinsics-enable} is the default. + +@cindex -fmil-intrinsics-delete option +@cindex options, -fmil-intrinsics-delete +@item -fmil-intrinsics-delete +@cindex -fmil-intrinsics-hide option +@cindex options, -fmil-intrinsics-hide +@item -fmil-intrinsics-hide +@cindex -fmil-intrinsics-disable option +@cindex options, -fmil-intrinsics-disable +@item -fmil-intrinsics-disable +@cindex -fmil-intrinsics-enable option +@cindex options, -fmil-intrinsics-enable +@item -fmil-intrinsics-enable +@cindex MIL-STD 1753 +@cindex intrinsics, MIL-STD 1753 +Specify status of MIL-STD-1753-specific intrinsics. +@samp{-fmil-intrinsics-enable} is the default. + +@cindex -funix-intrinsics-delete option +@cindex options, -funix-intrinsics-delete +@item -funix-intrinsics-delete +@cindex -funix-intrinsics-hide option +@cindex options, -funix-intrinsics-hide +@item -funix-intrinsics-hide +@cindex -funix-intrinsics-disable option +@cindex options, -funix-intrinsics-disable +@item -funix-intrinsics-disable +@cindex -funix-intrinsics-enable option +@cindex options, -funix-intrinsics-enable +@item -funix-intrinsics-enable +@cindex UNIX intrinsics +@cindex intrinsics, UNIX +Specify status of UNIX intrinsics. +@samp{-funix-intrinsics-enable} is the default. + +@cindex -fvxt-intrinsics-delete option +@cindex options, -fvxt-intrinsics-delete +@item -fvxt-intrinsics-delete +@cindex -fvxt-intrinsics-hide option +@cindex options, -fvxt-intrinsics-hide +@item -fvxt-intrinsics-hide +@cindex -fvxt-intrinsics-disable option +@cindex options, -fvxt-intrinsics-disable +@item -fvxt-intrinsics-disable +@cindex -fvxt-intrinsics-enable option +@cindex options, -fvxt-intrinsics-enable +@item -fvxt-intrinsics-enable +@cindex VXT intrinsics +@cindex intrinsics, VXT +Specify status of VXT intrinsics. +@samp{-fvxt-intrinsics-enable} is the default. + +@cindex -ffixed-line-length-@var{n} option +@cindex options, -ffixed-line-length-@var{n} +@item -ffixed-line-length-@var{n} +@cindex source file format +@cindex line length +@cindex length of source lines +@cindex fixed-form line length +Set column after which characters are ignored in typical fixed-form +lines in the source file, and through which spaces are assumed (as +if padded to that length) after the ends of short fixed-form lines. + +@cindex card image +@cindex extended-source option +Popular values for @var{n} include 72 (the +standard and the default), 80 (card image), and 132 (corresponds +to ``extended-source'' options in some popular compilers). +@var{n} may be @samp{none}, meaning that the entire line is meaningful +and that continued character constants never have implicit spaces appended +to them to fill out the line. +@samp{-ffixed-line-length-0} means the same thing as +@samp{-ffixed-line-length-none}. + +@xref{Source Form}, for more information. +@end table + +@node Warning Options +@section Options to Request or Suppress Warnings +@cindex options to control warnings +@cindex warning messages +@cindex messages, warning +@cindex suppressing warnings + +Warnings are diagnostic messages that report constructions which +are not inherently erroneous but which are risky or suggest there +might have been an error. + +You can request many specific warnings with options beginning @samp{-W}, +for example @samp{-Wimplicit} to request warnings on implicit +declarations. Each of these specific warning options also has a +negative form beginning @samp{-Wno-} to turn off warnings; +for example, @samp{-Wno-implicit}. This manual lists only one of the +two forms, whichever is not the default. + +These options control the amount and kinds of warnings produced by GNU +Fortran: + +@table @code +@cindex syntax checking +@cindex -fsyntax-only option +@cindex options, -fsyntax-only +@item -fsyntax-only +Check the code for syntax errors, but don't do anything beyond that. + +@cindex -pedantic option +@cindex options, -pedantic +@item -pedantic +Issue warnings for uses of extensions to ANSI FORTRAN 77. +@samp{-pedantic} also applies to C-language constructs where they +occur in GNU Fortran source files, such as use of @samp{\e} in a +character constant within a directive like @samp{#include}. + +Valid ANSI FORTRAN 77 programs should compile properly with or without +this option. +However, without this option, certain GNU extensions and traditional +Fortran features are supported as well. +With this option, many of them are rejected. + +Some users try to use @samp{-pedantic} to check programs for strict ANSI +conformance. +They soon find that it does not do quite what they want---it finds some +non-ANSI practices, but not all. +However, improvements to @code{g77} in this area are welcome. + +@cindex -pedantic-errors option +@cindex options, -pedantic-errors +@item -pedantic-errors +Like @samp{-pedantic}, except that errors are produced rather than +warnings. + +@cindex -fpedantic option +@cindex options, -fpedantic +@item -fpedantic +Like @samp{-pedantic}, but applies only to Fortran constructs. + +@cindex -w option +@cindex options, -w +@item -w +Inhibit all warning messages. + +@cindex -Wno-globals option +@cindex options, -Wno-globals +@item -Wno-globals +@cindex global names, warning +@cindex warnings, global names +Inhibit warnings about use of a name as both a global name +(a subroutine, function, or block data program unit, or a +common block) and implicitly as the name of an intrinsic +in a source file. + +Also inhibit warnings about inconsistent invocations and/or +definitions of global procedures (function and subroutines). +Such inconsistencies include different numbers of arguments +and different types of arguments. + +@cindex -Wimplicit option +@cindex options, -Wimplicit +@item -Wimplicit +@cindex implicit declaration, warning +@cindex warnings, implicit declaration +@cindex -u option +@cindex /WARNINGS=DECLARATIONS switch +@cindex IMPLICIT NONE, similar effect +@cindex effecting IMPLICIT NONE +Warn whenever a variable, array, or function is implicitly +declared. +Has an effect similar to using the @code{IMPLICIT NONE} statement +in every program unit. +(Some Fortran compilers provide this feature by an option +named @samp{-u} or @samp{/WARNINGS=DECLARATIONS}.) + +@cindex -Wunused option +@cindex options, -Wunused +@item -Wunused +@cindex unused variables +@cindex variables, unused +Warn whenever a variable is unused aside from its declaration. + +@cindex -Wuninitialized option +@cindex options, -Wuninitialized +@item -Wuninitialized +@cindex uninitialized variables +@cindex variables, uninitialized +Warn whenever an automatic variable is used without first being initialized. + +These warnings are possible only in optimizing compilation, +because they require data-flow information that is computed only +when optimizing. If you don't specify @samp{-O}, you simply won't +get these warnings. + +These warnings occur only for variables that are candidates for +register allocation. Therefore, they do not occur for a variable +@c that is declared @code{VOLATILE}, or +whose address is taken, or whose size +is other than 1, 2, 4 or 8 bytes. Also, they do not occur for +arrays, even when they are in registers. + +Note that there might be no warning about a variable that is used only +to compute a value that itself is never used, because such +computations may be deleted by data-flow analysis before the warnings +are printed. + +These warnings are made optional because GNU Fortran is not smart +enough to see all the reasons why the code might be correct +despite appearing to have an error. Here is one example of how +this can happen: + +@example +SUBROUTINE DISPAT(J) +IF (J.EQ.1) I=1 +IF (J.EQ.2) I=4 +IF (J.EQ.3) I=5 +CALL FOO(I) +END +@end example + +@noindent +If the value of @code{J} is always 1, 2 or 3, then @code{I} is +always initialized, but GNU Fortran doesn't know this. Here is +another common case: + +@example +SUBROUTINE MAYBE(FLAG) +LOGICAL FLAG +IF (FLAG) VALUE = 9.4 +@dots{} +IF (FLAG) PRINT *, VALUE +END +@end example + +@noindent +This has no bug because @code{VALUE} is used only if it is set. + +@cindex -Wall option +@cindex options, -Wall +@item -Wall +@cindex all warnings +@cindex warnings, all +The @samp{-Wunused} and @samp{-Wuninitialized} options combined. +These are all the +options which pertain to usage that we recommend avoiding and that we +believe is easy to avoid. +(As more warnings are added to @code{g77}, some might +be added to the list enabled by @samp{-Wall}.) +@end table + +The remaining @samp{-W@dots{}} options are not implied by @samp{-Wall} +because they warn about constructions that we consider reasonable to +use, on occasion, in clean programs. + +@table @code +@c @item -W +@c Print extra warning messages for these events: +@c +@c @itemize @bullet +@c @item +@c If @samp{-Wall} or @samp{-Wunused} is also specified, warn about unused +@c arguments. +@c +@c @end itemize +@c +@cindex -Wsurprising option +@cindex options, -Wsurprising +@item -Wsurprising +Warn about ``suspicious'' constructs that are interpreted +by the compiler in a way that might well be surprising to +someone reading the code. +These differences can result in subtle, compiler-dependent +(even machine-dependent) behavioral differences. +The constructs warned about include: + +@itemize @bullet +@item +Expressions having two arithmetic operators in a row, such +as @samp{X*-Y}. +Such a construct is nonstandard, and can produce +unexpected results in more complicated situations such +as @samp{X**-Y*Z}. +@code{g77}, along with many other compilers, interprets +this example differently than many programmers, and a few +other compilers. +Specifically, @code{g77} interprets @samp{X**-Y*Z} as +@samp{(X**(-Y))*Z}, while others might think it should +be interpreted as @samp{X**(-(Y*Z))}. + +A revealing example is the constant expression @samp{2**-2*1.}, +which @code{g77} evaluates to .25, while others might evaluate +it to 0., the difference resulting from the way precedence affects +type promotion. + +(The @samp{-fpedantic} option also warns about expressions +having two arithmetic operators in a row.) + +@item +Expressions with a unary minus followed by an operand and then +a binary operator other than plus or minus. +For example, @samp{-2**2} produces a warning, because +the precedence is @samp{-(2**2)}, yielding -4, not +@samp{(-2)**2}, which yields 4, and which might represent +what a programmer expects. + +An example of an expression producing different results +in a surprising way is @samp{-I*S}, where @var{I} holds +the value @samp{-2147483648} and @var{S} holds @samp{0.5}. +On many systems, negating @var{I} results in the same +value, not a positive number, because it is already the +lower bound of what an @code{INTEGER(KIND=1)} variable can hold. +So, the expression evaluates to a positive number, while +the ``expected'' interpretation, @samp{(-I)*S}, would +evaluate to a negative number. + +Even cases such as @samp{-I*J} produce warnings, +even though, in most configurations and situations, +there is no computational difference between the +results of the two interpretations---the purpose +of this warning is to warn about differing interpretations +and encourage a better style of coding, not to identify +only those places where bugs might exist in the user's +code. + +@cindex DO statement +@cindex statements, DO +@item +@code{DO} loops with @code{DO} variables that are not +of integral type---that is, using @code{REAL} +variables as loop control variables. +Although such loops can be written to work in the +``obvious'' way, the way @code{g77} is required by the +Fortran standard to interpret such code is likely to +be quite different from the way many programmers expect. +(This is true of all @code{DO} loops, but the differences +are pronounced for non-integral loop control variables.) + +@xref{Loops}, for more information. +@end itemize + +@cindex -Werror option +@cindex options, -Werror +@item -Werror +Make all warnings into errors. + +@cindex -W option +@cindex options, -W +@item -W +@cindex extra warnings +@cindex warnings, extra +Turns on ``extra warnings'' and, if optimization is specified +via @samp{-O}, the @samp{-Wuninitialized} option. +(This might change in future versions of @code{g77}.) + +``Extra warnings'' are issued for: + +@itemize @bullet +@item +@cindex unused parameters +@cindex parameters, unused +@cindex unused arguments +@cindex arguments, unused +@cindex unused dummies +@cindex dummies, unused +Unused parameters to a procedure (when @samp{-Wunused} also is +specified). + +@item +@cindex overflow +Overflows involving floating-point constants (not available +for certain configurations). +@end itemize +@end table + +@xref{Warning Options,,Options to Request or Suppress Warnings, +gcc,Using and Porting GNU CC}, for information on more options offered +by the GBE shared by @code{g77}, @code{gcc}, and other GNU compilers. + +Some of these have no effect when compiling programs written in Fortran: + +@table @code +@cindex -Wcomment option +@cindex options, -Wcomment +@item -Wcomment +@cindex -Wformat option +@cindex options, -Wformat +@item -Wformat +@cindex -Wparentheses option +@cindex options, -Wparentheses +@item -Wparentheses +@cindex -Wswitch option +@cindex options, -Wswitch +@item -Wswitch +@cindex -Wtraditional option +@cindex options, -Wtraditional +@item -Wtraditional +@cindex -Wshadow option +@cindex options, -Wshadow +@item -Wshadow +@cindex -Wid-clash-@var{len} option +@cindex options, -Wid-clash-@var{len} +@item -Wid-clash-@var{len} +@cindex -Wlarger-than-@var{len} option +@cindex options, -Wlarger-than-@var{len} +@item -Wlarger-than-@var{len} +@cindex -Wconversion option +@cindex options, -Wconversion +@item -Wconversion +@cindex -Waggregate-return option +@cindex options, -Waggregate-return +@item -Waggregate-return +@cindex -Wredundant-decls option +@cindex options, -Wredundant-decls +@item -Wredundant-decls +@cindex unsupported warnings +@cindex warnings, unsupported +These options all could have some relevant meaning for +GNU Fortran programs, but are not yet supported. +@end table + +@node Debugging Options +@section Options for Debugging Your Program or GNU Fortran +@cindex options, debugging +@cindex debugging information options + +GNU Fortran has various special options that are used for debugging +either your program or @code{g77}. + +@table @code +@cindex -g option +@cindex options, -g +@item -g +Produce debugging information in the operating system's native format +(stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging +information. + +@cindex common blocks +@cindex equivalence areas +@cindex missing debug features +Support for this option in Fortran programs is incomplete. +In particular, names of variables and arrays in common blocks +or that are storage-associated via @code{EQUIVALENCE} are +unavailable to the debugger. + +However, version 0.5.19 of @code{g77} does provide this information +in a rudimentary way, as controlled by the +@samp{-fdebug-kludge} option. + +@xref{Code Gen Options,,Options for Code Generation Conventions}, +for more information. +@end table + +@xref{Debugging Options,,Options for Debugging Your Program or GNU CC, +gcc,Using and Porting GNU CC}, for more information on debugging options. + +@node Optimize Options +@section Options That Control Optimization +@cindex optimize options +@cindex options, optimization + +Most Fortran users will want to use no optimization when +developing and testing programs, and use @samp{-O} or @samp{-O2} when +compiling programs for late-cycle testing and for production use. + +The following flags have particular applicability when +compiling Fortran programs: + +@table @code +@cindex -malign-double option +@cindex options, -malign-double +@item -malign-double +(Intel 386 architecture only.) + +Noticeably improves performance of @code{g77} programs making +heavy use of @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}) data +on some systems. +In particular, systems using Pentium, Pentium Pro, 586, and +686 implementations +of the i386 architecture execute programs faster when +@code{REAL(KIND=2)} (@code{DOUBLE PRECISION}) data are +aligned on 64-bit boundaries +in memory. + +This option can, at least, make benchmark results more consistent +across various system configurations, versions of the program, +and data sets. + +@emph{Note:} The warning in the @code{gcc} documentation about +this option does not apply, generally speaking, to Fortran +code compiled by @code{g77}. + +@emph{Also note:} Apparently due to a @code{gcc} backend bug, +@samp{-malign-double} does not align stack-allocated data (such as +local variables neither @code{SAVE}d nor reckoned to take up too +much space to put on the stack). + +@emph{Also also note:} The negative form of @samp{-malign-double} +is @samp{-mno-align-double}, not @samp{-benign-double}. + +@cindex -ffloat-store option +@cindex options, -ffloat-store +@item -ffloat-store +@cindex IEEE conformance +@cindex conformance, IEEE +Might help a Fortran program that depends on exact IEEE conformance +on some machines, but might slow down a program that doesn't. + +@cindex -fforce-mem option +@cindex options, -fforce-mem +@item -fforce-mem +@cindex -fforce-addr option +@cindex options, -fforce-addr +@item -fforce-addr +@cindex loops, speeding up +@cindex speeding up loops +Might improve optimization of loops. + +@cindex -fno-inline option +@cindex options, -fno-inline +@item -fno-inline +@cindex in-line compilation +@cindex compilation, in-line +Don't compile statement functions inline. +Might reduce the size of a program unit---which might be at +expense of some speed (though it should compile faster). +Note that if you are not optimizing, no functions can be expanded inline. + +@cindex -ffast-math option +@cindex options, -ffast-math +@item -ffast-math +@cindex IEEE conformance +@cindex conformance, IEEE +Might allow some programs designed to not be too dependent +on IEEE behavior for floating-point to run faster, or die trying. + +@cindex -fstrength-reduce option +@cindex options, -fstrength-reduce +@item -fstrength-reduce +@cindex loops, speeding up +@cindex speeding up loops +Might make some loops run faster. + +@cindex -frerun-cse-after-loop option +@cindex options, -frerun-cse-after-loop +@item -frerun-cse-after-loop +@cindex -fexpensive-optimizations option +@cindex options, -fexpensive-optimizations +@item -fexpensive-optimizations +@cindex -fdelayed-branch option +@cindex options, -fdelayed-branch +@item -fdelayed-branch +@cindex -fschedule-insns option +@cindex options, -fschedule-insns +@item -fschedule-insns +@cindex -fschedule-insns2 option +@cindex options, -fschedule-insns2 +@item -fschedule-insns2 +@cindex -fcaller-saves option +@cindex options, -fcaller-saves +@item -fcaller-saves +Might improve performance on some code. + +@cindex -funroll-loops option +@cindex options, -funroll-loops +@item -funroll-loops +@cindex loops, unrolling +@cindex unrolling loops +Definitely improves performance on some code. + +@cindex -funroll-all-loops option +@cindex options, -funroll-all-loops +@item -funroll-all-loops +Definitely improves performance on some code. + +@item -fno-move-all-movables +@cindex -fno-move-all-movables option +@cindex options, -fno-move-all-movables +@item -fno-reduce-all-givs +@cindex -fno-reduce-all-givs option +@cindex options, -fno-reduce-all-givs +@item -fno-rerun-loop-opt +@cindex -fno-rerun-loop-opt option +@cindex options, -fno-rerun-loop-opt +Each of these might improve performance on some code. + +Analysis of Fortran code optimization and the resulting +optimizations triggered by the above options were +contributed by Toon Moene (@email{toon@@moene.indiv.nluug.nl}). + +These three options are intended to be removed someday, once +they have helped determine the efficacy of various +approaches to improving the performance of Fortran code. + +Please let us know how use of these options affects +the performance of your production code. +We're particularly interested in code that runs faster +when these options are @emph{disabled}, and in +non-Fortran code that benefits when they are +@emph{enabled} via the above @code{gcc} command-line options. +@end table + +@xref{Optimize Options,,Options That Control Optimization, +gcc,Using and Porting GNU CC}, for more information on options +to optimize the generated machine code. + +@node Preprocessor Options +@section Options Controlling the Preprocessor +@cindex preprocessor options +@cindex options, preprocessor +@cindex cpp program +@cindex programs, cpp + +These options control the C preprocessor, which is run on each C source +file before actual compilation. + +@xref{Preprocessor Options,,Options Controlling the Preprocessor, +gcc,Using and Porting GNU CC}, for information on C preprocessor options. + +@cindex INCLUDE directive +@cindex directive, INCLUDE +Some of these options also affect how @code{g77} processes the +@code{INCLUDE} directive. +Since this directive is processed even when preprocessing +is not requested, it is not described in this section. +@xref{Directory Options,,Options for Directory Search}, for +information on how @code{g77} processes the @code{INCLUDE} directive. + +However, the @code{INCLUDE} directive does not apply +preprocessing to the contents of the included file itself. + +Therefore, any file that contains preprocessor directives +(such as @code{#include}, @code{#define}, and @code{#if}) +must be included via the @code{#include} directive, not +via the @code{INCLUDE} directive. +Therefore, any file containing preprocessor directives, +if included, is necessarily included by a file that itself +contains preprocessor directives. + +@node Directory Options +@section Options for Directory Search +@cindex directory options +@cindex options, directory search +@cindex search path + +These options affect how the @code{cpp} preprocessor searches +for files specified via the @code{#include} directive. +Therefore, when compiling Fortran programs, they are meaningful +when the preproecssor is used. + +@cindex INCLUDE directive +@cindex directive, INCLUDE +Some of these options also affect how @code{g77} searches +for files specified via the @code{INCLUDE} directive, +although files included by that directive are not, +themselves, preprocessed. +These options are: + +@table @code +@cindex -I- option +@cindex options, -I- +@item -I- +@cindex -Idir option +@cindex options, -Idir +@item -I@var{dir} +@cindex directory search paths for inclusion +@cindex inclusion, directory search paths for +@cindex searching for included files +These affect interpretation of the @code{INCLUDE} directive +(as well as of the @code{#include} directive of the @code{cpp} +preprocessor). + +Note that @samp{-I@var{dir}} must be specified @emph{without} any +spaces between @samp{-I} and the directory name---that is, +@samp{-Ifoo/bar} is valid, but @samp{-I foo/bar} +is rejected by the @code{g77} compiler (though the preprocessor supports +the latter form). +@c this is due to toplev.c's inflexible option processing +Also note that the general behavior of @samp{-I} and +@code{INCLUDE} is pretty much the same as of @samp{-I} with +@code{#include} in the @code{cpp} preprocessor, with regard to +looking for @file{header.gcc} files and other such things. + +@xref{Directory Options,,Options for Directory Search, +gcc,Using and Porting GNU CC}, for information on the @samp{-I} option. +@end table + +@node Code Gen Options +@section Options for Code Generation Conventions +@cindex code generation conventions +@cindex options, code generation +@cindex run-time options + +These machine-independent options control the interface conventions +used in code generation. + +Most of them have both positive and negative forms; the negative form +of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only +one of the forms is listed---the one which is not the default. You +can figure out the other form by either removing @samp{no-} or adding +it. + +@table @code +@cindex -fno-automatic option +@cindex options, -fno-automatic +@item -fno-automatic +@cindex SAVE statement +@cindex statements, SAVE +Treat each program unit as if the @code{SAVE} statement was specified +for every local variable and array referenced in it. +Does not affect common blocks. +(Some Fortran compilers provide this option under +the name @samp{-static}.) + +@cindex -finit-local-zero option +@cindex options, -finit-local-zero +@item -finit-local-zero +@cindex DATA statement +@cindex statements, DATA +@cindex initialization of local variables +@cindex variables, initialization of +@cindex uninitialized variables +@cindex variables, uninitialized +Specify that variables and arrays that are local to a program unit +(not in a common block and not passed as an argument) are to be initialized +to binary zeros. + +Since there is a run-time penalty for initialization of variables +that are not given the @code{SAVE} attribute, it might be a +good idea to also use @samp{-fno-automatic} with @samp{-finit-local-zero}. + +@cindex -fno-f2c option +@cindex options, -fno-f2c +@item -fno-f2c +@cindex @code{f2c} compatibility +@cindex compatibility, @code{f2c} +Do not generate code designed to be compatible with code generated +by @code{f2c}; use the GNU calling conventions instead. + +The @code{f2c} calling conventions require functions that return +type @code{REAL(KIND=1)} to actually return the C type @code{double}, +and functions that return type @code{COMPLEX} to return the +values via an extra argument in the calling sequence that points +to where to store the return value. +Under the GNU calling conventions, such functions simply return +their results as they would in GNU C---@code{REAL(KIND=1)} functions +return the C type @code{float}, and @code{COMPLEX} functions +return the GNU C type @code{complex} (or its @code{struct} +equivalent). + +This does not affect the generation of code that interfaces with the +@code{libf2c} library. + +However, because the @code{libf2c} library uses @code{f2c} +calling conventions, @code{g77} rejects attempts to pass +intrinsics implemented by routines in this library as actual +arguments when @samp{-fno-f2c} is used, to avoid bugs when +they are actually called by code expecting the GNU calling +conventions to work. + +For example, @samp{INTRINSIC ABS;CALL FOO(ABS)} is +rejected when @samp{-fno-f2c} is in force. +(Future versions of the @code{g77} run-time library might +offer routines that provide GNU-callable versions of the +routines that implement the @code{f2c}-callable intrinsics +that may be passed as actual arguments, so that +valid programs need not be rejected when @samp{-fno-f2c} +is used.) + +@strong{Caution:} If @samp{-fno-f2c} is used when compiling any +source file used in a program, it must be used when compiling +@emph{all} Fortran source files used in that program. + +@c seems kinda dumb to tell people about an option they can't use -- jcb +@c then again, we want users building future-compatible libraries with it. +@cindex -ff2c-library option +@cindex options, -ff2c-library +@item -ff2c-library +Specify that use of @code{libf2c} is required. +This is the default for the current version of @code{g77}. + +Currently it is not +valid to specify @samp{-fno-f2c-library}. +This option is provided so users can specify it in shell +scripts that build programs and libraries that require the +@code{libf2c} library, even when being compiled by future +versions of @code{g77} that might otherwise default to +generating code for an incompatible library. + +@cindex -fno-underscoring option +@cindex options, -fno-underscoring +@item -fno-underscoring +@cindex underscores +@cindex symbol names, underscores +@cindex transforming symbol names +@cindex symbol names, transforming +Do not transform names of entities specified in the Fortran +source file by appending underscores to them. + +With @samp{-funderscoring} in effect, @code{g77} appends two underscores +to names with underscores and one underscore to external names with +no underscores. (@code{g77} also appends two underscores to internal +names with underscores to avoid naming collisions with external names. +The @samp{-fno-second-underscore} option disables appending of the +second underscore in all cases.) + +This is done to ensure compatibility with code produced by many +UNIX Fortran compilers, including @code{f2c}, which perform the +same transformations. + +Use of @samp{-fno-underscoring} is not recommended unless you are +experimenting with issues such as integration of (GNU) Fortran into +existing system environments (vis-a-vis existing libraries, tools, and +so on). + +For example, with @samp{-funderscoring}, and assuming other defaults like +@samp{-fcase-lower} and that @samp{j()} and @samp{max_count()} are +external functions while @samp{my_var} and @samp{lvar} are local variables, +a statement like + +@smallexample +I = J() + MAX_COUNT (MY_VAR, LVAR) +@end smallexample + +@noindent +is implemented as something akin to: + +@smallexample +i = j_() + max_count__(&my_var__, &lvar); +@end smallexample + +With @samp{-fno-underscoring}, the same statement is implemented as: + +@smallexample +i = j() + max_count(&my_var, &lvar); +@end smallexample + +Use of @samp{-fno-underscoring} allows direct specification of +user-defined names while debugging and when interfacing @code{g77}-compiled +code with other languages. + +Note that just because the names match does @emph{not} mean that the +interface implemented by @code{g77} for an external name matches the +interface implemented by some other language for that same name. +That is, getting code produced by @code{g77} to link to code produced +by some other compiler using this or any other method can be only a +small part of the overall solution---getting the code generated by +both compilers to agree on issues other than naming can require +significant effort, and, unlike naming disagreements, linkers normally +cannot detect disagreements in these other areas. + +Also, note that with @samp{-fno-underscoring}, the lack of appended +underscores introduces the very real possibility that a user-defined +external name will conflict with a name in a system library, which +could make finding unresolved-reference bugs quite difficult in some +cases---they might occur at program run time, and show up only as +buggy behavior at run time. + +In future versions of @code{g77}, we hope to improve naming and linking +issues so that debugging always involves using the names as they appear +in the source, even if the names as seen by the linker are mangled to +prevent accidental linking between procedures with incompatible +interfaces. + +@cindex -fno-second-underscore option +@cindex options, -fno-second-underscore +@item -fno-second-underscore +@cindex underscores +@cindex symbol names, underscores +@cindex transforming symbol names +@cindex symbol names, transforming +Do not append a second underscore to names of entities specified +in the Fortran source file. + +This option has no effect if @samp{-fno-underscoring} is +in effect. + +Otherwise, with this option, an external name such as @samp{MAX_COUNT} +is implemented as a reference to the link-time external symbol +@samp{max_count_}, instead of @samp{max_count__}. + +@cindex -fno-ident option +@cindex options, -fno-ident +@item -fno-ident +Ignore the @samp{#ident} directive. + +@cindex -fzeros option +@cindex options, -fzeros +@item -fzeros +Treat initial values of zero as if they were any other value. + +As of version 0.5.18, @code{g77} normally treats @code{DATA} and +other statements that are used to specify initial values of zero +for variables and arrays as if no values were actually specified, +in the sense that no diagnostics regarding multiple initializations +are produced. + +This is done to speed up compiling of programs that initialize +large arrays to zeros. + +Use @samp{-fzeros} to revert to the simpler, slower behavior +that can catch multiple initializations by keeping track of +all initializations, zero or otherwise. + +@emph{Caution:} Future versions of @code{g77} might disregard this option +(and its negative form, the default) or interpret it somewhat +differently. +The interpretation changes will affect only non-standard +programs; standard-conforming programs should not be affected. + +@cindex -fdebug-kludge option +@cindex options, -fdebug-kludge +@item -fdebug-kludge +Emit information on @code{COMMON} and @code{EQUIVALENCE} members +that might help users of debuggers work around lack of proper debugging +information on such members. + +As of version 0.5.19, @code{g77} offers this option to emit +information on members of aggregate areas to help users while debugging. +This information consists of establishing the type and contents of each +such member so that, when a debugger is asked to print the contents, +the printed information provides rudimentary debugging information. +This information identifies the name of the aggregate area (either the +@code{COMMON} block name, or the @code{g77}-assigned name for the +@code{EQUIVALENCE} name) and the offset, in bytes, of the member from +the beginning of the area. + +Using @code{gdb}, this information is not coherently displayed in the Fortran +language mode, so temporarily switching to the C language mode to display the +information is suggested. +Use @samp{set language c} and @samp{set language fortran} to accomplish this. + +For example: + +@smallexample + COMMON /X/A,B + EQUIVALENCE (C,D) + CHARACTER XX*50 + EQUIVALENCE (I,XX(20:20)) + END + +GDB is free software and you are welcome to distribute copies of it + under certain conditions; type "show copying" to see the conditions. +There is absolutely no warranty for GDB; type "show warranty" for details. +GDB 4.16 (lm-gnits-dwim), Copyright 1996 Free Software Foundation, Inc... +(gdb) b MAIN__ +Breakpoint 1 at 0t1200000201120112: file cd.f, line 5. +(gdb) r +Starting program: /home/user/a.out + +Breakpoint 1, MAIN__ () at cd.f:5 +Current language: auto; currently fortran +(gdb) set language c +Warning: the current language does not match this frame. +(gdb) p a +$2 = "At (COMMON) `x_' plus 0 bytes" +(gdb) p b +$3 = "At (COMMON) `x_' plus 4 bytes" +(gdb) p c +$4 = "At (EQUIVALENCE) `__g77_equiv_c' plus 0 bytes" +(gdb) p d +$5 = "At (EQUIVALENCE) `__g77_equiv_c' plus 0 bytes" +(gdb) p i +$6 = "At (EQUIVALENCE) `__g77_equiv_xx' plus 20 bytes" +(gdb) p xx +$7 = "At (EQUIVALENCE) `__g77_equiv_xx' plus 1 bytes" +(gdb) set language fortran +(gdb) +@end smallexample + +@noindent +Use @samp{-fdebug-kludge} to generate this information, +which might make some programs noticeably larger. + +@emph{Caution:} Future versions of @code{g77} might disregard this option +(and its negative form). +Current plans call for this to happen when published versions of @code{g77} +and @code{gdb} exist that provide proper access to debugging information on +@code{COMMON} and @code{EQUIVALENCE} members. + +@cindex -fno-emulate-complex option +@cindex options, -fno-emulate-complex +@item -fno-emulate-complex +Implement @code{COMPLEX} arithmetic using the facilities in +the @code{gcc} back end that provide direct support of +@code{complex} arithmetic, instead of emulating the arithmetic. + +@code{gcc} has some known problems in its back-end support +for @code{complex} arithmetic, due primarily to the support not being +completed as of version 2.7.2.2. +Other front ends for the @code{gcc} back end avoid this problem +by emulating @code{complex} arithmetic at a higher level, so the +back end sees arithmetic on the real and imaginary components. +To make @code{g77} more portable to systems where @code{complex} +support in the @code{gcc} back end is particularly troublesome, +@code{g77} now defaults to performing the same kinds of emulations +done by these other front ends. + +Use @samp{-fno-emulate-complex} to try the @code{complex} support +in the @code{gcc} back end, in case it works and produces faster +programs. +So far, all the known bugs seem to involve compile-time crashes, +rather than the generation of incorrect code. + +Use of this option should not affect how Fortran code compiled +by @code{g77} works in terms of its interfaces to other code, +e.g. that compiled by @code{f2c}. + +@emph{Caution:} Future versions of @code{g77} are likely to change +the default for this option to +@samp{-fno-emulate-complex}, and perhaps someday ignore both forms +of this option. + +Also, it is possible that use of the @samp{-fno-emulate-complex} option +could result in incorrect code being silently produced by @code{g77}. +But, this is generally true of compilers anyway, so, as usual, test +the programs you compile before assuming they are working. + +@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 +@item -falias-check +@item -fargument-alias +@item -fargument-noalias +@item -fno-argument-noalias-global +These options specify to what degree aliasing +(overlap) +is permitted between +arguments (passed as pointers) and @code{COMMON} (external, or +public) storage. + +The default for Fortran code, as mandated by the FORTRAN 77 and +Fortran 90 standards, is @samp{-fargument-noalias-global}. +The default for code written in the C language family is +@samp{-fargument-alias}. + +Note that, on some systems, compiling with @samp{-fforce-addr} in +effect can produce more optimal code when the default aliasing +options are in effect (and when optimization is enabled). + +@xref{Aliasing Assumed To Work}, for detailed information on the implications +of compiling Fortran code that depends on the ability to alias dummy +arguments. + +@cindex -fno-globals option +@cindex options, -fno-globals +@item -fno-globals +@cindex global names, warning +@cindex warnings, global names +Disable diagnostics about inter-procedural +analysis problems, such as disagreements about the +type of a function or a procedure's argument, +that might cause a compiler crash when attempting +to inline a reference to a procedure within a +program unit. +(The diagnostics themselves are still produced, but +as warnings, unless @samp{-Wno-globals} is specified, +in which case no relevant diagnostics are produced.) + +Further, this option disables such inlining, to +avoid compiler crashes resulting from incorrect +code that would otherwise be diagnosed. + +As such, this option might be quite useful when +compiling existing, ``working'' code that happens +to have a few bugs that do not generally show +themselves, but @code{g77} exposes via a +diagnostic. + +Use of this option therefore has the effect of +instructing @code{g77} to behave more like it did +up through version 0.5.19.1, when it paid little or +no attention to disagreements between program units +about a procedure's type and argument information, +and when it performed no inlining of procedures +(except statement functions). + +Without this option, @code{g77} defaults to performing +the potentially inlining procedures as it started doing +in version 0.5.20, but as of version 0.5.21, it also +diagnoses disagreements that might cause such inlining +to crash the compiler. +@end table + +@xref{Code Gen Options,,Options for Code Generation Conventions, +gcc,Using and Porting GNU CC}, for information on more options +offered by the GBE +shared by @code{g77}, @code{gcc}, and other GNU compilers. + +Some of these do @emph{not} work when compiling programs written in Fortran: + +@table @code +@cindex -fpcc-struct-return option +@cindex options, -fpcc-struct-return +@item -fpcc-struct-return +@cindex -freg-struct-return option +@cindex options, -freg-struct-return +@item -freg-struct-return +You should not use these except strictly the same way as you +used them to build the version of @code{libf2c} with which +you will be linking all code compiled by @code{g77} with the +same option. + +@cindex -fshort-double option +@cindex options, -fshort-double +@item -fshort-double +This probably either has no effect on Fortran programs, or +makes them act loopy. + +@cindex -fno-common option +@cindex options, -fno-common +@item -fno-common +Do not use this when compiling Fortran programs, +or there will be Trouble. + +@cindex -fpack-struct option +@cindex options, -fpack-struct +@item -fpack-struct +This probably will break any calls to the @code{libf2c} library, +at the very least, even if it is built with the same option. +@end table + +@node Environment Variables +@section Environment Variables Affecting GNU Fortran +@cindex environment variables + +GNU Fortran currently does not make use of any environment +variables to control its operation above and beyond those +that affect the operation of @code{gcc}. + +@xref{Environment Variables,,Environment Variables Affecting GNU CC, +gcc,Using and Porting GNU CC}, for information on environment +variables. + +@include news.texi + +@node Changes +@chapter User-visible Changes +@cindex versions, recent +@cindex recent versions +@cindex changes, user-visible +@cindex user-visible changes + +This section describes changes to @code{g77} that are visible +to the programmers who actually write and maintain Fortran +code they compile with @code{g77}. +Information on changes to installation procedures, +changes to the documentation, and bug fixes is +not provided here, unless it is likely to affect how +users use @code{g77}. +@xref{News,,News About GNU Fortran}, for information on +such changes to @code{g77}. + +To find out about existing bugs and ongoing plans for GNU +Fortran, retrieve @url{ftp://alpha.gnu.ai.mit.edu/g77.plan} +or, if you cannot do that, email +@email{fortran@@gnu.ai.mit.edu} asking for a recent copy of the +GNU Fortran @file{.plan} file. + +@heading In 0.5.21: +@itemize @bullet +@item +When the @samp{-W} option is specified, @code{gcc}, @code{g77}, +and other GNU compilers that incorporate the @code{gcc} +back end as modified by @code{g77}, issue +a warning about integer division by constant zero. + +@item +New option @samp{-Wno-globals} disables warnings +about ``suspicious'' use of a name both as a global +name and as the implicit name of an intrinsic, and +warnings about disagreements over the number or natures of +arguments passed to global procedures, or the +natures of the procedures themselves. + +The default is to issue such warnings, which are +new as of this version of @code{g77}. + +@item +New option @samp{-fno-globals} disables diagnostics +about potentially fatal disagreements +analysis problems, such as disagreements over the +number or natures of arguments passed to global +procedures, or the natures of those procedures themselves. + +The default is to issue such diagnostics and flag +the compilation as unsuccessful. +With this option, the diagnostics are issued as +warnings, or, if @samp{-Wno-globals} is specified, +are not issued at all. + +This option also disables inlining of global procedures, +to avoid compiler crashes resulting from coding errors +that these diagnostics normally would identify. + +@item +Fix @code{libU77} routines that accept file names +to strip trailing spaces from them, for consistency +with other implementations. + +@item +Fix @code{SIGNAL} intrinsic so it accepts an +optional third @samp{Status} argument. + +@item +Make many changes to @code{libU77} intrinsics to +support existing code more directly. + +Such changes include allowing both subroutine and +function forms of many routines, changing @code{MCLOCK()} +and @code{TIME()} to return @code{INTEGER(KIND=1)} values, +introducing @code{MCLOCK8()} and @code{TIME8()} to +return @code{INTEGER(KIND=2)} values, +and placing functions that are intended to perform +side effects in a new intrinsic group, @code{badu77}. + +@item +Add options @samp{-fbadu77-intrinsics-delete}, +@samp{-fbadu77-intrinsics-hide}, and so on. + +@item +Add @code{INT2} and @code{INT8} intrinsics. + +@item +Add @code{CPU_TIME} intrinsic. + +@item +@code{CTIME} intrinsic now accepts any @code{INTEGER} +argument, not just @code{INTEGER(KIND=2)}. +@end itemize + +@heading In 0.5.20: +@itemize @bullet +@item +The @samp{-fno-typeless-boz} option is now the default. + +This option specifies that non-decimal-radix +constants using the prefixed-radix form (such as @samp{Z'1234'}) +are to be interpreted as @code{INTEGER(KIND=1)} constants. +Specify @samp{-ftypeless-boz} to cause such +constants to be interpreted as typeless. + +(Version 0.5.19 introduced @samp{-fno-typeless-boz} and +its inverse.) + +@xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}, +for information on the @samp{-ftypeless-boz} option. + +@item +Options @samp{-ff90-intrinsics-enable} and +@samp{-fvxt-intrinsics-enable} now are the +defaults. + +Some programs might use names that clash with +intrinsic names defined (and now enabled) by these +options or by the new @code{libU77} intrinsics. +Users of such programs might need to compile them +differently (using, for example, @samp{-ff90-intrinsics-disable}) +or, better yet, insert appropriate @code{EXTERNAL} +statements specifying that these names are not intended +to be names of intrinsics. + +@item +The @samp{ALWAYS_FLUSH} macro is no longer defined when +building @code{libf2c}, which should result in improved +I/O performance, especially over NFS. + +@emph{Note:} If you have code that depends on the behavior +of @code{libf2c} when built with @samp{ALWAYS_FLUSH} defined, +you will have to modify @code{libf2c} accordingly before +building it from this and future versions of @code{g77}. + +@xref{Output Assumed To Flush}, for more information. + +@item +Dave Love's implementation of @code{libU77} has been +added to the version of @code{libf2c} distributed with +and built by @code{g77}. +@code{g77} now knows about the routines in this library +as intrinsics. + +@item +New option @samp{-fvxt} specifies that the +source file is written in VXT Fortran, instead of GNU Fortran. + +@xref{VXT Fortran}, for more information on the constructs +recognized when the @samp{-fvxt} option is specified. + +@item +The @samp{-fvxt-not-f90} option has been deleted, +along with its inverse, @samp{-ff90-not-vxt}. + +If you used one of these deleted options, you should +re-read the pertinent documentation to determine which +options, if any, are appropriate for compiling your +code with this version of @code{g77}. + +@xref{Other Dialects}, for more information. + +@item +The @samp{-fugly} option now issues a warning, as it +likely will be removed in a future version. + +(Enabling all the @samp{-fugly-*} options is unlikely +to be feasible, or sensible, in the future, +so users should learn to specify only those +@samp{-fugly-*} options they really need for a +particular source file.) + +@item +The @samp{-fugly-assumed} option, introduced in +version 0.5.19, has been changed to +better accommodate old and new code. +@xref{Ugly Assumed-Size Arrays}, for more information. + +@item +Related to supporting Alpha (AXP) machines, the @code{LOC()} +intrinsic and @code{%LOC()} construct now return +values of @code{INTEGER(KIND=0)} type, +as defined by the GNU Fortran language. + +This type is wide enough +(holds the same number of bits) +as the character-pointer type on the machine. + +On most systems, this won't make a noticable difference, +whereas on Alphas and other systems with 64-bit pointers, +the @code{INTEGER(KIND=0)} type is equivalent to @code{INTEGER(KIND=2)} +(often referred to as @code{INTEGER*8}) +instead of the more common @code{INTEGER(KIND=1)} +(often referred to as @code{INTEGER*4}). + +@item +Emulate @code{COMPLEX} arithmetic in the @code{g77} front +end, to avoid bugs in @code{complex} support in the +@code{gcc} back end. +New option @samp{-fno-emulate-complex} +causes @code{g77} to revert the 0.5.19 behavior. + +@item +Dummy arguments are no longer assumed to potentially alias +(overlap) +other dummy arguments or @code{COMMON} areas when any of +these are defined (assigned to) by Fortran code. + +This can result in faster and/or smaller programs when +compiling with optimization enabled, though on some +systems this effect is observed only when @samp{-fforce-addr} +also is specified. + +New options @samp{-falias-check}, @samp{-fargument-alias}, +@samp{-fargument-noalias}, +and @samp{-fno-argument-noalias-global} control the +way @code{g77} handles potential aliasing. + +@xref{Aliasing Assumed To Work}, for detailed information on why the +new defaults might result in some programs no longer working the way they +did when compiled by previous versions of @code{g77}. + +@item +New option @samp{-fugly-assign} specifies that the +same memory locations are to be used to hold the +values assigned by both statements @samp{I = 3} and +@samp{ASSIGN 10 TO I}, for example. +(Normally, @code{g77} uses a separate memory location +to hold assigned statement labels.) + +@xref{Ugly Assigned Labels}, for more information. + +@item +@code{FORMAT} and @code{ENTRY} statements now are allowed to +precede @code{IMPLICIT NONE} statements. + +@item +Enable full support of @code{INTEGER(KIND=2)} +(often referred to as @code{INTEGER*8}) +available in +@code{libf2c} and @file{f2c.h} so that @code{f2c} users +may make full use of its features via the @code{g77} +version of @file{f2c.h} and the @code{INTEGER(KIND=2)} +support routines in the @code{g77} version of @code{libf2c}. + +@item +Improve @code{g77} driver and @code{libf2c} so that @samp{g77 -v} +yields version information on the library. + +@item +The @code{SNGL} and @code{FLOAT} intrinsics now are +specific intrinsics, instead of synonyms for the +generic intrinsic @code{REAL}. + +@item +New intrinsics have been added. +These are @code{REALPART}, @code{IMAGPART}, +@code{COMPLEX}, +@code{LONG}, and @code{SHORT}. + +@item +A new group of intrinsics, @samp{gnu}, has been added +to contain the new @code{REALPART}, @code{IMAGPART}, +and @code{COMPLEX} intrinsics. +An old group, @samp{dcp}, has been removed. +@end itemize + +@heading In 0.5.19: + +@itemize @bullet +@item +A temporary kludge option provides bare-bones information on +@code{COMMON} and @code{EQUIVALENCE} members at debug time. +@xref{Code Gen Options,,Options for Code Generation Conventions}, +for information on the @samp{-fdebug-kludge} option. + +@item +New @samp{-fonetrip} option specifies FORTRAN-66-style +one-trip @code{DO} loops. + +@item +New @samp{-fno-silent} option causes names of program units +to be printed as they are compiled, in a fashion similar to +UNIX @code{f77} and @code{f2c}. + +@item +New @samp{-fugly-assumed} option specifies that arrays +dimensioned via @samp{DIMENSION X(1)}, for example, are to be +treated as assumed-size. + +@item +New @samp{-fno-typeless-boz} option specifies that non-decimal-radix +constants using the prefixed-radix form (such as @samp{Z'1234'}) +are to be interpreted as @code{INTEGER(KIND=1)} constants. + +@item +New @samp{-ff66} option is a ``shorthand'' option that specifies +behaviors considered appropriate for FORTRAN 66 programs. + +@item +New @samp{-ff77} option is a ``shorthand'' option that specifies +behaviors considered appropriate for UNIX @code{f77} programs. + +@item +New @samp{-fugly-comma} and @samp{-fugly-logint} options provided +to perform some of what @samp{-fugly} used to do. +@samp{-fugly} and @samp{-fno-ugly} are now ``shorthand'' options, +in that they do nothing more than enable (or disable) other +@samp{-fugly-*} options. + +@item +Change code generation for list-directed I/O so it allows +for new versions of @code{libf2c} that might return non-zero +status codes for some operations previously assumed to always +return zero. + +This change not only affects how @code{IOSTAT=} variables +are set by list-directed I/O, it also affects whether +@code{END=} and @code{ERR=} labels are reached by these +operations. + +@item +Add intrinsic support for new @code{FTELL} and @code{FSEEK} +procedures in @code{libf2c}. + +@item +Add options @samp{--help} and @samp{--version} to the +@code{g77} command, to conform to GNU coding guidelines. +Also add printing of @code{g77} version number when +the @samp{--verbose} (@samp{-v}) option is used. +@end itemize + +@heading In 0.5.18: + +@itemize @bullet +@item +The @code{BYTE} and @code{WORD} statements now are supported, +to a limited extent. + +@item +@code{INTEGER*1}, @code{INTEGER*2}, @code{INTEGER*8}, +and their @code{LOGICAL} +equivalents, now are supported to a limited extent. +Among the missing elements are complete intrinsic and constant +support. + +@item +Support automatic arrays in procedures. +For example, @samp{REAL A(N)}, where @samp{A} is +not a dummy argument, specifies that @samp{A} is +an automatic array. +The size of @samp{A} is calculated from the value +of @samp{N} each time the procedure is called, +that amount of space is allocated, and that space +is freed when the procedure returns to its caller. + +@item +Add @samp{-fno-zeros} option, enabled by default, +to reduce compile-time CPU and memory usage for +code that provides initial zero values for variables +and arrays. + +@item +Introduce three new options that apply to all compilations +by @code{g77}-aware GNU compilers---@samp{-fmove-all-movables}, +@samp{-freduce-all-givs}, and @samp{-frerun-loop-opt}---which +can improve the run-time performance of some programs. + +@item +Replace much of the existing documentation with a single +Info document. + +@item +New option @samp{-fno-second-underscore}. +@end itemize + +@heading In 0.5.17: + +@itemize @bullet +@item +The @code{ERF()} and @code{ERFC()} intrinsics now are generic +intrinsics, mapping to @code{ERF}/@code{DERF} and +@code{ERFC}/@code{DERFC}, respectively. +@emph{Note:} Use @samp{INTRINSIC ERF,ERFC} in any code that +might reference these as generic intrinsics, to +improve the likelihood of diagnostics (instead of subtle run-time +bugs) when using compilers that don't support these as intrinsics. + +@item +New option @samp{-Wsurprising}. + +@item +DO loops with non-@code{INTEGER} variables now diagnosed only when +@samp{-Wsurprising} specified. +Previously, this was diagnosed @emph{unless} @samp{-fpedantic} or +@samp{-fugly} was specified. +@end itemize + +@heading In 0.5.16: + +@itemize @bullet +@item +@code{libf2c} changed to output a leading zero (0) digit for floating-point +values output via list-directed and formatted output (to bring @code{g77} +more into line with many existing Fortran implementations---the +ANSI FORTRAN 77 standard leaves this choice to the implementation). + +@item +@code{libf2c} no longer built with debugging information +intact, making it much smaller. + +@item +Automatic installation of the @code{g77} command now works. + +@item +Diagnostic messages now more informative, a la @code{gcc}, +including messages like @samp{In function `foo':} and @samp{In file +included from...:}. + +@item +New group of intrinsics called @samp{unix}, including @code{ABORT}, +@code{DERF}, @code{DERFC}, @code{ERF}, @code{ERFC}, @code{EXIT}, +@code{FLUSH}, @code{GETARG}, @code{GETENV}, @code{SIGNAL}, and +@code{SYSTEM}. + +@item +@samp{-funix-intrinsics-@{delete,hide,disable,enable@}} +options added. + +@item +@samp{-fno-underscoring} option added. + +@item +@samp{--driver} option added to the @code{g77} command. + +@item +Support for the @code{gcc} options @samp{-fident} and @samp{-fno-ident} +added. + +@item +@samp{g77 -v} returns much more version info, making the submission +of better bug reports easily. + +@item +Many improvements to the @code{g77} command to better fulfill its role as +a front-end to the @code{gcc} driver. +For example, @code{g77} now +recognizes @samp{--verbose} as a verbose way of specifying @samp{-v}. + +@item +Compiling preprocessed (@file{*.F} and @file{*.fpp}) files now +results in better diagnostics and debugging information, as the +source-location info now is passed all the +way through the compilation process instead of being lost. +@end itemize + +@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 @url{http://kumo.swcp.com/fortran/F77_std/f77_std.html} +or in @url{ftp://ftp.ast.cam.ac.uk/pub/michael/}. +It offers some extensions that are popular among users +of UNIX @code{f77} and @code{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 +@url{http://www.fortran.com/fortran/Books/}.) + +Part of what defines a particular implementation of a Fortran +system, such as @code{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 @code{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:: +@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 @code{g77} itself is in beta test. +Some current features of the language might later +be redefined as dialects of Fortran supported by @code{g77} +when better ways to express these features are added to @code{g77}, +for example. +Such features would still be supported by +@code{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} (@code{g77}). + +For example, @code{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 @code{g77} accepts +when compiling using the prevailing defaults and what this +document describes as being part of the language. + +Future versions of @code{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 @code{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 @code{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 @code{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, heteregenous 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 @code{g77} can use to resolve +conflicts between various camps of Fortran users. +If these two camps disagree about what a particular construct should +mean, @code{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 @code{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 @code{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 @code{g77}). + +@node Standard Support +@section ANSI FORTRAN 77 Standard Support +@cindex ANSI FORTRAN 77 support +@cindex standard support +@cindex support for ANSI 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 @code{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 + +@code{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 + +@code{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 @code{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 @code{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, @code{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, @code{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 @code{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 @code{g77}. + +@item +Bugs in the system. +@end itemize + +Despite these ``loopholes'', the availability of a clear specification +of the language of programs submitted to @code{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 @code{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.) + +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 comments, trailing +@cindex trailing comments +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 semicolons +@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, @code{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:: +@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 +Semicolon (@samp{;}) + +@item +Exclamation point (@samp{!}) + +@item +Double quote (@samp{"}) + +@item +Backslash (@samp{\}) + +@item +Question mark (@samp{?}) + +@item +Hash mark (@samp{#}) + +@item +Ampersand (@samp{&}) + +@item +Percent sign (@samp{%}) + +@item +Underscore (@samp{_}) + +@item +Open angle (@samp{<}) + +@item +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 blanks (spaces) +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 form +@cindex files, 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 12 (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 blanks (spaces) +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 lines, number of +@cindex lines, continuation +@cindex number of continuation lines +@cindex limits on 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 + +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. + +(@code{g77} treats it as a filename that it searches for +in the current directory and/or directories specified +via the @samp{-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 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 +@code{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 @code{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 +@code{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. +@code{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 @code{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 @code{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 +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 @code{g77}---avoid writing code depending +on them while @code{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.) + +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.) + +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 @code{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, @code{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(%LOC(I))}, and +in fact might compile to identical code. + +However, @samp{CALL FOO(%LOC(I))} emphatically means ``pass the +address of @samp{I} in memory''. +While @samp{CALL FOO(I)} might use that same approach in a +particular version of @code{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(%LOC(I))} +using the same version or compiler. + +@xref{Debugging and Interfacing}, for detailed information on +how this particular version of @code{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 @code{f2c}. + +@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 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. + +@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 @code{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 + +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, @code{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 @code{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, @code{g77} passes +all arguments +(other than variables and arrays of type @code{CHARACTER}) +by reference. +Future versions of, or dialects supported by, @code{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 @code{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 @code{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, @code{g77} passes +all variables and arrays of type @code{CHARACTER} +by descriptor. +Future versions of, or dialects supported by, @code{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 @code{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 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 Contact via Internet email: burley@@gnu.ai.mit.edu +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 @samp{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 @samp{JCB002} +above will confirm that: + +@itemize @bullet +@item +Digital Semiconductor (``DEC'') Alpha OSF/1, HP-UX 10.0.1, AIX 3.2.5 +@code{f77} compilers all implement @samp{Interp 1}. + +@item +IRIX 5.3 @code{f77} compiler implements @samp{Interp 2}. + +@item +Solaris 2.5, SunOS 4.1.3, DECstation ULTRIX 4.3, +and IRIX 6.1 @code{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 REAL intrinsic +@cindex intrinsics, REAL +@cindex AIMAG intrinsic +@cindex intrinsics, 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 @samp{-ff90} is in effect, +@code{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 CMPLX intrinsic +@cindex intrinsics, 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 +@code{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 @code{f77}/@code{f2c} Intrinsics + +The bit-manipulation intrinsics supported by traditional +@code{f77} and by @code{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 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 @code{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 symbolic names +@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 underscores + +Underscores (@samp{_}) are accepted in symbol names after the first +character (which must be a letter). + +@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 +@code{g77} supports in whole or in part. + +Any of the features listed below might be disallowed by +@code{g77} unless some command-line option is specified. +Currently, some of the features are accepted using the +default invocation of @code{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 form +@cindex files, 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 +(@code{f2c}, Digital (``DEC'') Fortran, and so on), though a cleaner default +definition along with more +flexibility offered by command-line options is likely to be offered +in version 0.6. + +This section describes how @code{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 @code{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 characters + +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 @code{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. + +@code{g77} effectively +translates tabs to the appropriate number of spaces (a la the default +for the UNIX @code{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. + +Note that this default behavior probably will change for version 0.6, +when it will presumably be available via a command-line option. +The default as of version 0.6 is planned to be a ``pure visual'' +model, where tabs are immediately +converted to spaces and otherwise have no effect, so the way a typical +user sees source lines produces a consistent result no matter how the +spacing in those source lines is actually implemented via tabs, spaces, +and trailing tabs/spaces before newline. +Command-line options are likely to be added to specify whether all or +just-tabbed lines are to be extended to 132 or full input-line length, +and perhaps even an option will be added to specify the truncated-line +behavior to which some Digital compilers default (and which affects +the way continued character/Hollerith constants are interpreted). + +@node Short Lines +@subsection Short Lines +@cindex short source lines +@cindex space-padding +@cindex spaces +@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). + +@code{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 @samp{-ffixed-line-length-none}, for example. + +@node Long Lines +@subsection Long Lines +@cindex long source lines +@cindex truncation +@cindex lines, long +@cindex source lines, long + +Source lines longer than the applicable length are truncated to that +length. +Currently, @code{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 @samp{-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 @code{f2c}. + +@node Trailing Comment +@section Trailing Comment + +@code{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 + +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, @code{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 @samp{-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: @code{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{libf2c}, +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 -- +@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 @samp{BN} and @samp{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 @samp{-fcase-strict-upper} to specify this +combination. + +Number 43 is like Number 22 except all input must be lowercase. Use +@samp{-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 @samp{-fcase-upper} to specify this combination. + +Number 66 is the ``canonical'' UNIX model whereby all the source is +translated to lowercase. +Use @samp{-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 +@code{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 @code{g77} +someday, and is considered a VXT Fortran feature. + +The @samp{-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 + +@code{g77} treats double-quote (@samp{"}) +as beginning an octal constant of @code{INTEGER(KIND=1)} type +when the @code{-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 @code{-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 exclamation points +@cindex continuation character +@cindex characters, continuation +@cindex comment character +@cindex characters, comment + +@code{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 @code{-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 @samp{-ff90} option is not specified. +The features enabled by @samp{-ff90} are intended to be those that, +when @samp{-ff90} is not specified, would have another +meaning to @code{g77}---usually meaning something invalid in the +GNU Fortran language. + +So, the purpose of @samp{-ff90} is not to specify whether @code{g77} is +to gratuitously reject Fortran 90 constructs. +The @samp{-pedantic} option specified with @samp{-fno-f90} is intended +to do that, although its implementation is certainly incomplete at +this point. + +When @samp{-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 @samp{-ff90} is specified. +@end itemize + +@node Pedantic Compilation +@section Pedantic Compilation +@cindex pedantic compilation +@cindex compilation, pedantic + +The @samp{-fpedantic} command-line option specifies that @code{g77} +is to warn about code that is not standard-conforming. +This is useful for finding +some extensions @code{g77} accepts that other compilers might not accept. +(Note that the @samp{-pedantic} and @samp{-pedantic-errors} options +always imply @samp{-fpedantic}.) + +With @samp{-fno-f90} in force, ANSI FORTRAN 77 is used as the standard +for conforming code. +With @samp{-ff90} in force, Fortran 90 is used. + +The constructs for which @code{g77} issues diagnostics when @samp{-fpedantic} +and @samp{-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 -- +@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 @samp{-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 @samp{-fpedantic} is specified along with @samp{-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 @samp{-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. + +@emph{Note:} The @samp{-fugly} option, which currently serves +as shorthand to enable all of the distensions below, is likely to +be removed in a future version of @code{g77}. +That's because it's likely new distensions will be added that +conflict with existing ones in terms of assigning meaning to +a given chunk of code. +(Also, it's pretty clear that users should not use @samp{-fugly} +as shorthand when the next release of @code{g77} might add a +distension to that that causes their existing code, when recompiled, +to behave differently---perhaps even fail to compile or run +correctly.) + +@menu +* Ugly Implicit Argument Conversion:: Disabled via @samp{-fno-ugly-args}. +* Ugly Assumed-Size Arrays:: Enabled via @samp{-fugly-assumed}. +* Ugly Null Arguments:: Enabled via @samp{-fugly-comma}. +* Ugly Complex Part Extraction:: Enabled via @samp{-fugly-complex}. +* Ugly Conversion of Initializers:: Disabled via @samp{-fno-ugly-init}. +* Ugly Integer Conversions:: Enabled via @samp{-fugly-logint}. +* Ugly Assigned Labels:: Enabled via @samp{-fugly-assign}. +@end menu + +@node Ugly Implicit Argument Conversion +@subsection Implicit Argument Conversion +@cindex Hollerith constants +@cindex constants, Hollerith + +The @samp{-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 @samp{-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, @samp{-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 @samp{-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 @samp{-ff90} in effect, these intrinsics return +the unconverted real and imaginary parts (respectively) +of their argument. + +With @samp{-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 @samp{-fno-ugly-complex} is in effect, because the +meaning is clear. + +@code{g77} enforces this restriction, unless @samp{-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 commas +@cindex commas, trailing +@cindex null arguments +@cindex arguments, null + +The @samp{-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 a procedure other than a +statement function, and use of an empty list of arguments 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 @samp{-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 @samp{-fugly-comma} +in force as compared to its behavior when compiled +with the default, @samp{-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 @samp{-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 +@samp{-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 +@samp{-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 +@samp{-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 @samp{-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 @samp{-fugly-assign} option forces @code{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, @code{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-@samp{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 @code{g77} unless @samp{-fugly-assign} +is specified on the command-line, ensuring that the value of @code{I} +referenced in the second line is whatever value @code{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 @samp{-fugly-assign} is specified, +@code{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 @code{g77} actually writing valid pointers +to these variables, however. +While @code{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, @code{g77}, supports programs written +in the GNU Fortran language and in some other dialects of Fortran. + +Some aspects of how @code{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:: +* Compiler Types:: +* Compiler Constants:: +* Compiler Intrinsics:: +@end menu + +@node Compiler Limits +@section Compiler Limits +@cindex limits, compiler +@cindex compiler limits + +@code{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 +For example, some other Fortran compiler have an option +(such as @samp{-Nl@var{x}}) to increase the limit on the +number of continuation lines. +Also, some Fortran compilation systems have an option +(such as @samp{-Nx@var{x}}) to increase the limit on the +number of external symbols. + +@code{g77}, @code{gcc}, and GNU @code{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 +@code{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 well be lifted in a future version. + +@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.) + +@code{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 @code{gcc} and @code{g77}. +@code{g77} warns about such +situations when it encounters them.) + +@code{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 +@code{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 @code{gcc} built in the same release as @code{g77} (and +which was therefore used to build both the @code{g77} compiler +components and the @code{libf2c} 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 @code{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 @code{gcc} type as @code{INTEGER(KIND=2)}. + +@cindex INTEGER(KIND=3) type +@cindex types, INTEGER(KIND=3) +@item INTEGER(KIND=3) +Same @code{gcc} type as signed @code{char}. + +@cindex LOGICAL(KIND=3) type +@cindex types, LOGICAL(KIND=3) +@item LOGICAL(KIND=3) +Same @code{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 @code{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 @code{gcc} type occupies @var{n} times the storage +space of a @code{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 @code{g77}---avoid writing code depending +on them. + +Other types supported by @code{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 @code{gcc} already supports, @code{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 + +@code{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. + +@code{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 @code{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 + +@code{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, @code{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 @code{g77} to pretend as though the intrinsics in +that group do not exist at all, whereas disabling it tells @code{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 +@item badu77 +UNIX intrinsics having inappropriate forms (usually functions that +have intended side effects). + +@item gnu +Intrinsics the GNU Fortran language supports that are extensions to +the Fortran standards (77 and 90). + +@item f2c +Intrinsics supported by AT&T's @code{f2c} converter and/or @code{libf2c}. + +@item f90 +Fortran 90 intrinsics. + +@item mil +MIL-STD 1753 intrinsics (@code{MVBITS}, @code{IAND}, @code{BTEST}, and so on). + +@item unix +UNIX intrinsics (@code{IARGC}, @code{EXIT}, @code{ERF}, and so on). + +@item vxt +VAX/VMS FORTRAN (current as of v4) intrinsics. +@end table + +@node Other Intrinsics +@subsection Other Intrinsics +@cindex intrinsics, others +@cindex other intrinsics + +@code{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, @code{g77} generates code that is +object-compatible with code generated by a version of +@code{f2c} configured (with, for example, @file{f2c.h} definitions) +to be generally compatible with @code{g77} as built by @code{gcc}. +(Normally, @code{f2c} will, by default, conform to the appropriate +configuration, but it is possible that older or perhaps even newer +versions of @code{f2c}, or versions having certain configuration changes +to @code{f2c} internals, will produce object files that are +incompatible with @code{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 +@code{g77} uses the same run-time library, @code{libf2c}, used by +@code{f2c}. + +Other compilers might or might not generate code that +is object-compatible with @code{libf2c} and current @code{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 @code{f2c} Compatibility + +Specifying @samp{-fno-f2c} allows @code{g77} to generate, in +some cases, faster code, by not needing to allow to the possibility +of linking with code compiled by @code{f2c}. + +For example, this affects how @code{REAL(KIND=1)}, +@code{COMPLEX(KIND=1)}, and @code{COMPLEX(KIND=2)} functions are called. +With @samp{-fno-f2c}, they are +compiled as returning the appropriate @code{gcc} type +(@code{float}, @code{__complex__ float}, @code{__complex__ double}, +in many configurations). + +With @samp{-ff2c} in force, they +are compiled differently (with perhaps slower run-time performance) +to accommodate the restrictions inherent in @code{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 @samp{-ff2c} in force +might produce faster code than using @samp{-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 @code{f2c} compatibility is a fairly static target to achieve, +though not necessarily perfectly so, since, like @code{g77}, it is +still being improved. +However, specifying @samp{-fno-f2c} causes @code{g77} +to generate code that will probably be incompatible with code +generated by future versions of @code{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 @code{g77} +or @code{f2c}, especially when using options such as @samp{-fno-f2c}. + +Therefore, if you are using @code{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 @code{g77}, +you might want to stick with @code{f2c} compatibility for now, and +carefully watch for any announcements about changes to the +@code{f2c}/@code{libf2c} interface that might affect existing programs +(thus requiring recompilation). + +It is probable that a future version of @code{g77} will not, +by default, generate object files compatible with @code{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 @code{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. + +@node Compilers Other Than f2c +@section Compilers Other Than @code{f2c} + +On systems with Fortran compilers other than @code{f2c} and @code{g77}, +code compiled by @code{g77} is not expected to work +well with code compiled by the native compiler. +(This is true for @code{f2c}-compiled objects as well.)@ +Libraries compiled with the native compiler probably will have +to be recompiled with @code{g77} to be used with @code{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 @code{g77} to call a procedure the linker @code{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 @code{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 @code{g77} in @code{f2c} +compatibility mode, i.e.@ not using @samp{-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 @code{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 +@samp{-lstdc++}, @samp{-lg++} or whatever. +If you need to use another +driver program (or @code{ld} directly), +you can find out what linkage +options @code{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, @samp{f2c} from +@url{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 @code{f2c}}. + +To use @code{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 +@code{f2c} program on your path. + +Something else that might be useful is @samp{cfortran.h} from +@url{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 @code{f2c} mode with +@code{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 +@code{g77} code---calling and/or being +called from Fortran---should @samp{#include <f2c.h>} to define the C +versions of the Fortran types. +Don't assume Fortran @code{INTEGER} types +correspond to C @samp{int}s, for instance; instead, declare them as +@code{integer}, a type defined by @file{f2c.h}. +@file{f2c.h} is installed where @code{gcc} will find it by +default, assuming you use a copy of @code{gcc} compatible with +@code{g77}, probably built at the same time as @code{g77}. + +@node f2c Skeletons and Prototypes +@subsection Generating Skeletons and Prototypes with @code{f2c} + +@pindex f2c +@cindex -fno-second-underscore +A simple and foolproof way to write @code{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 @samp{END} statements. +Then run @code{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 f2c conventions, such as not using @code{doublereal} as +the return type of a @code{REAL} @code{FUNCTION}.) + +@pindex ftnchek +@code{f2c} also can help with calling Fortran from C, using its +@samp{-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 @samp{ftnchek} tool from @url{ftp://ftp.netlib.org/fortran} 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 @code{g77}) and +C handle arrays. + +@node C++ Considerations +@subsection C++ Considerations + +@cindex C++ +@code{f2c} can be used to generate suitable code for compilation with a +C++ system using the @samp{-C++} option. +The important thing about linking @code{g77}-compiled +code with C++ is that the prototypes for the @code{g77} +routines must specify C linkage to avoid name mangling. +So, use an @samp{extern "C"} declaration. +@code{f2c}'s @samp{-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 runtime initialization +@cindex initialization, runtime +Unlike with some runtime systems, it shouldn't be necessary (unless there are +bugs) to use a Fortran main program to ensure the +runtime---specifically the i/o system---is initialized. +However, to use +the @code{g77} intrinsics @code{GETARG()} and @code{IARGC()} the +@code{main()} routine from the @file{libf2c} library must be used, either +explicitly or implicitly by using a Fortran main program. +This +@code{main()} program calls @code{MAIN__()} (where the names are C-type +@code{extern} names, i.e.@ not mangled). +You need to provide this +nullary procedure as the entry point for your C code if using +@file{libf2c}'s @code{main}. +In some cases it might be necessary to +provide a dummy version of this to avoid linkers complaining about +failure to resolve @code{MAIN__()} if linking against @file{libf2c} and +not using @code{main()} from it. + +@include install.texi + +@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 @code{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 @code{g77}-compiled code generally +requires some understanding of the way @code{g77} compiles code for +various constructs. + +Similarly, using a debugger to debug @code{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 +@code{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 @code{g77}, sometimes even to using certain compiler options +with @code{g77} (such as @samp{-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 @code{g77}. +This information +is provided primarily to make debugging of code generated by this +particular release of @code{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 @code{g77} as they +are installed, because new versions can change the behaviors +described in this section. + +@menu +* Main Program Unit:: How @code{g77} compiles a main program unit. +* Procedures:: How @code{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 @code{g77} performs complex arithmetic. +* Arrays:: Dealing with (possibly multi-dimensional) arrays. +* Adjustable Arrays:: Special consideration for adjustable arrays. +* Alternate Entry Points:: How @code{g77} implements alternate @code{ENTRY}. +* Alternate Returns:: How @code{g77} handles alternate returns. +* Assigned Statement Labels:: How @code{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 @code{g77} compiles a main program unit, it gives it the public +procedure name @samp{MAIN__}. +The @code{libf2c} 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 @samp{MAIN__}. + +Generally, @code{g77} and @code{libf2c} 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 @code{g77} version 0.5.16 +includes a bug fix for @code{libf2c} 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 @code{g77} (or @code{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{libf2c}, found in the source +file @file{gcc/f/runtime/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 IARGC() intrinsic +@cindex intrinsics, IARGC() +@cindex GETARG() intrinsic +@cindex intrinsics, GETARG() +For example, @code{libf2c}'s @code{main()} sets up the information used by +the @code{IARGC} and @code{GETARG} intrinsics. +Bypassing @code{libf2c}'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{libf2c} 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 @samp{MAIN__}, and then run the program. +A convenient way to do so is to add the @code{gdb} command + +@example +tbreak MAIN__ +@end example + +@noindent +to the file @file{.gdbinit} in the directory in which you're debugging +(using @code{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 @samp{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, @code{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 +@code{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{gcc/f/runtime/f2c.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 @code{g77} +does not provide the trailing null bytes on the constant +strings (@code{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 + +@code{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}, @code{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 @samp{-ff2c} is in +force, @code{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 @samp{-fno-f2c} is in force, +@code{g77} implements a @code{COMPLEX} function as @code{gcc}'s +@samp{__complex__ float} or @samp{__complex__ double} function +(or an emulation thereof, when @samp{-femulate-complex} is in effect), +returning the result of the function in the same way as @code{gcc} would. + +For @code{REAL(KIND=1)}, when @samp{-ff2c} is in force, @code{g77} implements +a function that actually returns @code{REAL(KIND=2)} (typically +C's @code{double} type). +When @samp{-fno-f2c} is in force, @code{REAL(KIND=1)} +functions return @code{float}. + +@node Names +@section Names +@cindex symbol names +@cindex transformation of 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 @code{g77}, to generate code that is compatible with 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 @samp{-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 @samp{-funderscoring} is in force, any name (external or local) +that already has at least one underscore in it is +implemented by @code{g77} by appending two underscores. +(This second underscore can be disabled via the +@samp{-fno-second-underscore} option.)@ +External names are changed this way for @code{f2c} compatibility. +Local names are changed this way to avoid collisions with external names +that are different in the source code---@code{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 @code{g77} in this regard in the future---don't +write scripts depending on this behavior! +Also, consider experimenting with the @samp{-fno-underscoring} +option to try out debugging without having to massage names by +hand like this.) + +@code{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 @code{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, @code{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 @samp{-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 COMMON statement +@cindex statements, COMMON + +@code{g77} names and lays out @code{COMMON} areas the same way f2c does, +for compatibility with f2c. + +Currently, @code{g77} does not emit ``true'' debugging information for +members of a @code{COMMON} area, due to an apparent bug in the GBE. + +(As of Version 0.5.19, @code{g77} emits debugging information for such +members in the form of a constant string specifying the base name of +the aggregate area and the offset of the member in bytes from the start +of the area. +Use the @samp{-fdebug-kludge} option to enable this behavior. +In @code{gdb}, use @samp{set language c} before printing the value +of the member, then @samp{set language fortran} to restore the default +language, since @code{gdb} doesn't provide a way to print a readable +version of a character string in Fortran language mode. + +This kludge will be removed in a future version of @code{g77} that, +in conjunction with a contemporary version of @code{gdb}, +properly supports Fortran-language debugging, including access +to members of @code{COMMON} areas.) + +@xref{Code Gen Options,,Options for Code Generation Conventions}, +for information on the @samp{-fdebug-kludge} option. + +Moreover, @code{g77} currently implements a @code{COMMON} area such that its +type is an array of the C @code{char} data type. + +So, when debugging, you must know the offset into a @code{COMMON} area +for a particular item in that area, and you have to take into +account the appropriate multiplier for the respective sizes +of the types (as declared in your code) for the items preceding +the item in question as compared to the size of the @code{char} type. + +For example, using default implicit typing, the statement + +@example +COMMON I(15), R(20), T +@end example + +@noindent +results in a public 144-byte @code{char} array named @samp{_BLNK__} +with @samp{I} placed at @samp{_BLNK__[0]}, @samp{R} at @samp{_BLNK__[60]}, +and @samp{T} at @samp{_BLNK__[140]}. +(This is assuming that the target machine for +the compilation has 4-byte @code{INTEGER(KIND=1)} and @code{REAL(KIND=1)} +types.) + +@node Local Equivalence Areas +@section Local Equivalence Areas (EQUIVALENCE) +@cindex equivalence areas +@cindex local equivalence areas +@cindex EQUIVALENCE statement +@cindex statements, EQUIVALENCE + +@code{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. + +Currently, @code{g77} does not emit ``true'' debugging information for +members in a local @code{EQUIVALENCE} area, due to an apparent bug in the GBE. + +(As of Version 0.5.19, @code{g77} does emit debugging information for such +members in the form of a constant string specifying the base name of +the aggregate area and the offset of the member in bytes from the start +of the area. +Use the @samp{-fdebug-kludge} option to enable this behavior. +In @code{gdb}, use @samp{set language c} before printing the value +of the member, then @samp{set language fortran} to restore the default +language, since @code{gdb} doesn't provide a way to print a readable +version of a character string in Fortran language mode. + +This kludge will be removed in a future version of @code{g77} that, +in conjunction with a contemporary version of @code{gdb}, +properly supports Fortran-language debugging, including access +to members of @code{EQUIVALENCE} areas.) + +@xref{Code Gen Options,,Options for Code Generation Conventions}, +for information on the @samp{-fdebug-kludge} option. + +Moreover, @code{g77} implements a local @code{EQUIVALENCE} area such that its +type is an array of the C @code{char} data type. + +The name @code{g77} gives this array of @code{char} type is @samp{__g77_equiv_@var{x}}, +where @var{x} is the name of the item that is placed at the beginning (offset 0) +of this array. +If more than one such item is placed at the beginning, @var{x} is +the name that sorts to the top in an alphabetical sort of the list of +such items. + +When debugging, you must therefore access members of @code{EQUIVALENCE} +areas by specifying the appropriate @samp{__g77_equiv_@var{x}} +array section with the appropriate offset. +See the explanation of debugging @code{COMMON} blocks +for info applicable to debugging local @code{EQUIVALENCE} areas. + +(@emph{Note:} @code{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}, @code{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 of complex +@cindex COMPLEX statement +@cindex statements, COMPLEX + +As of 0.5.20, @code{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, @code{g77} implements these types using an +internal construct similar to C's @code{struct}, at least +as seen by the @code{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 +@code{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 @code{gdb}, this is accomplished via @samp{set lang c} and +either @samp{set lang fortran} or @samp{set lang auto}.) + +@emph{Note:} Compiling with the @samp{-fno-emulate-complex} option +avoids the debugging problem, but is known to cause other problems +like compiler crashes and generation of incorrect code, so it is +not recommended. + +@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 @code{f2c}, @code{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 @code{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, @code{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 @code{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 @code{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 @code{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. +@code{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 @code{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 @code{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. + +@code{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, @code{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 @code{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 @samp{-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 @code{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 @code{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 @code{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 @code{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)}, @code{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 @code{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; @code{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. +@code{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 @code{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 @code{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 @code{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{libf2c} 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 @samp{F_err} in @file{f/runtime/libI77/err.c} in the +@code{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 @code{g77} can be divided into two camps: + +@itemize @bullet +@item +Those writing new Fortran code to be compiled by @code{g77}. + +@item +Those using @code{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 @code{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 @code{f2c} is so great, why @code{g77}? +* Block Data and Libraries:: How @code{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 @code{f2c}, @code{g77} would have taken much longer to +do and probably not been as good for quite a while. +Sometimes people who notice how much @code{g77} depends on, and +documents encouragement to use, @code{f2c} ask why @code{g77} +was created if @code{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. +* Compiler Options:: Features helpful during development. +* 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 + +@code{g77} offers several extensions to the Fortran language that @code{f2c} +doesn't. + +However, @code{f2c} offers a few that @code{g77} doesn't, like +fairly complete support for @code{INTEGER*2}. +It is expected that @code{g77} will offer some or all of these missing +features at some time in the future. +(Version 0.5.18 of @code{g77} offers some rudimentary support for some +of these features.) + +@node Compiler Options +@subsection Compiler Options + +@code{g77} offers a whole bunch of compiler options that @code{f2c} doesn't. + +However, @code{f2c} offers a few that @code{g77} doesn't, like an +option to generate code to check array subscripts at run time. +It is expected that @code{g77} will offer some or all of these +missing options 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 @code{g77} should be able to compile code much faster than using +@code{f2c} in conjunction with the equivalent invocation of @code{gcc}. + +However, due to @code{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, @code{g77} +is noticeably faster compiling many Fortran source files than using +@code{f2c} in conjunction with @code{gcc}. + +@node Program Speed +@subsection Program Speed + +@code{g77} has the potential to better optimize code than @code{f2c}, +even when @code{gcc} is used to compile the output of @code{f2c}, +because @code{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 @code{g77} can gather, preserve, and transmit that information directly +to the GBE. + +For example, @code{g77} implements @code{ASSIGN} and assigned +@code{GOTO} using direct assignment of pointers to labels and direct +jumps to labels, whereas @code{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 @code{f2c} plus @code{gcc} +can generate code that is faster than @code{g77}. + +Version 0.5.18 of @code{g77} offered default +settings and options, via patches to the @code{gcc} +back end, that allow for better program speed, though +some of these improvements also affected the performance +of programs translated by @code{f2c} and then compiled +by @code{g77}'s version of @code{gcc}. + +Version 0.5.20 of @code{g77} offers further performance +improvements, at least one of which (alias analysis) is +not generally applicable to @code{f2c} (though @code{f2c} +could presumably be changed to also take advantage of +this new capability of the @code{gcc} back end, assuming +this is made available in an upcoming release of @code{gcc}). + +@node Ease of Debugging +@subsection Ease of Debugging + +Because @code{g77} compiles directly to assembler code like @code{gcc}, +instead of translating to an intermediate language (C) as does @code{f2c}, +support for debugging can be better for @code{g77} than @code{f2c}. + +However, although @code{g77} might be somewhat more ``native'' in terms of +debugging support than @code{f2c} plus @code{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, @code{g77} doesn't have to worry about reserved names +like @code{f2c} does. +Given @samp{FOR = WHILE}, @code{f2c} must necessarily +translate this to something @emph{other} than +@samp{for = while;}, because C reserves those words. + +However, @code{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 @code{g77} user should be able to access the variables directly, by name, +without having to traverse C-like structures and unions, while @code{f2c} +is unlikely to ever offer this ability (due to limitations in the +C language). + +However, due to apparent bugs in the back end, @code{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. +@code{g77} represents them to the debugger +using the same ``dimensionality'' as in the source code, while @code{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 @code{g77} can vary widely. +In some cases, it can actually +be an advantage that @code{f2c} converts everything to widely supported +C semantics. + +In fairness, @code{g77} could do many of the things @code{f2c} does +to get things working at least as well as @code{f2c}---for now, +the developers prefer making @code{g77} work the +way they think it is supposed to, and finding help improving the +other products (the back end of @code{gcc}; @code{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, +@code{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. + +@code{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 @code{g77} simply asks for fewer zeros from the operating +system than @code{f2c}. + +@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 @code{f2c} compatibility +@cindex compatibility, @code{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}. +@code{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, @code{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, @code{g77} outputs in the data section a static pointer to the +external name @samp{FOO}.) + +The implementation @code{g77} currently uses to make this work is +one of the few things not compatible with @code{f2c} as currently +shipped. +@code{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}, f2c doesn't generate a dummy procedure with the +name @samp{FOO}. +The upshot is that you shouldn't mix @code{f2c} and @code{g77} in +this particular case. +If you use f2c to compile @samp{BLOCK DATA FOO}, +then any @code{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 @code{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 @code{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 @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 @code{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 @code{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 @code{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 @code{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, @code{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 @code{g77}, use of @code{DO} loops +with @code{REAL} iteration +variables is not recommended. +Such use can be caught by specifying @samp{-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. + +@code{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:: +@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 @samp{-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. +(@code{g77} supports @code{IMPLICIT NONE}, as do almost all +FORTRAN 77 compilers.) + +Note that @samp{-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 @code{g77} for this behavior by specifying the +@samp{-finit-local-zero} option when compiling Fortran code. +(You might want to specify @samp{-fno-automatic} as well, +to avoid code-size inflation for non-optimized compilations.) + +Note that a program that works better when compiled with the +@samp{-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 @samp{-O -Wuninitialized} +options using @code{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 @code{g77} to assume @code{SAVE} is specified for all +relevant (local) variables and arrays by using the +@samp{-fno-automatic} option. + +Note that a program that works better when compiled with the +@samp{-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 @code{g77}. + +@node Unwanted Variables +@subsection Unwanted Variables + +The @samp{-Wunused} option can find bugs involving +implicit typing, sometimes +more easily than using @samp{-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 @samp{-W} also enables warnings regarding overflow +of floating-point constants under certain circumstances. + +@node Surprising Interpretations of Code +@subsection Surprising Interpretations of Code + +The @samp{-Wsuprising} 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 @code{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 @code{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 @samp{-falias-check}, @samp{-fargument-alias}, +@samp{-fargument-noalias}, +and @samp{-fno-argument-noalias-global} options, +introduced in version 0.5.20 and +@code{g77}'s version 2.7.2.2.f.2 of @code{gcc}, +control the assumptions regarding aliasing +(overlapping) +of writes and reads to main memory (core) made +by the @code{gcc} back end. + +They are effective only when compiling with @samp{-O} (specifying +any level other than @samp{-O0}) or with @samp{-falias-check}. + +The default for Fortran code is @samp{-fargument-noalias-global}. +(The default for C code and code written in other C-based languages +is @samp{-fargument-alias}. +These defaults apply regardless of whether you use @code{g77} or +@code{gcc} to compile your code.) + +Note that, on some systems, compiling with @samp{-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 @code{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 @samp{-fargument-alias} option, which causes the +compiler to revert to assumptions essentially the same as +made by versions of @code{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 @code{g77} +in a way that results in a faster executable. + +(You might want to try compiling with @samp{-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, @code{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 @code{g77}, though patches improving @code{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, @code{g77} configured its +version of the @code{libf2c} run-time library so that one of +its configuration macros, @samp{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, @code{g77} no longer configures @code{libf2c} +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{libf2c}, rebuild and reinstall @code{g77}, and +relink your programs with the modified library. + +(Ideally, @code{libf2c} would offer the choice at run-time, so +that a compile-time option to @code{g77} or @code{f2c} could +result in generating the appropriate calls to flushing or +non-flushing library routines.) + +@xref{Always Flush Output}, for information on how to modify +the @code{g77} source tree so that a version of @code{libf2c} +can be built and installed with the @samp{ALWAYS_FLUSH} macro defined. + +@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{libf2c}, used, and +distributed with, @code{g77}. + +The message means that your program has attempted to use a +file unit number that is out of the range accepted by +@code{libf2c}. +Normally, this range is 0 through 99, and the high end +of the range is controlled by a @code{libf2c} source-file +macro named @samp{MXUNIT}. + +If you can easily change your program to use unit numbers +in the range 0 through 99, you should do so. + +Otherwise, see @ref{Larger File Unit Numbers}, for information on how +to change @samp{MXUNIT} in @code{libf2c} so you can build and +install a new version of @code{libf2c} that supports the larger +unit numbers you need. + +@emph{Note:} While @code{libf2c} 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. + +@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 +@samp{-finit-local-zero} is not needed. + +Consider using @samp{-Wuninitialized} (which requires @samp{-O}) to +find likely candidates, but +do not specify @samp{-finit-local-zero} or @samp{-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 @samp{-Wuninitialized} (which requires @samp{-O}) +to find likely candidates, but +do not specify @samp{-finit-local-zero} or @samp{-fno-automatic}, +or this technique won't work. + +The default is @samp{-fautomatic}, which tells @code{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, @code{g77} supports only automatic arrays, not +@code{RECURSIVE} procedures or other means of explicitly +specifying that variables or arrays are automatic. + +@cindex -fugly option +@cindex options, -fugly +@item -fugly +Fix the source code so that @samp{-fno-ugly} will work. +Note that, for many programs, it is difficult to practically +avoid using the features enabled via @samp{-fugly-init}, and these +features pose the lowest risk of writing nonportable code, among the +various ``ugly'' features. + +@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 @samp{-f@var{group}-intrinsics-disable}. +@end table + +@node Faster Programs +@section Faster Programs +@cindex speeding up programs +@cindex programs, speeding up + +Aside from the usual @code{gcc} options, such as @samp{-O}, +@samp{-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 data, aligned +@cindex stack, aligned +@cindex aligned data +@cindex aligned stack +@cindex Pentium optimizations +@cindex optimizations, 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. + +There are a variety of approaches to use to address this problem, +in any combination: + +@itemize @bullet +@item +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. + +@item +Use the (x86-specific) @samp{-malign-double} option when compiling +programs. +This will align only static data (entities in @code{COMMON} or +local entities with the @code{SAVE} attribute), +but it should probably always be +used with Fortran code on the 586 and 686 architectures for best +performance. + +This feature of @samp{-malign-double} means it may actually be best to +use it with @samp{-fno-automatic} even though the latter usually +produces worse code; at least, doing so will tend to produce more +consistent run times. + +Using @samp{-malign-double} and @samp{-fno-automatic} together is +apparently the only way to ensure that all doubles are correctly aligned +on GNU x86 systems without having to change @code{g77} itself as +described in the next item. +(Note that the @code{gcc} C extension @samp{__attribute__ ((aligned (8))} +also won't double-align the datum to which it is applied if that is allocated +on the stack.) +It isn't clear whether this deficiency also applies to +non-GNU based x86 systems (Solaris, DGUX et al), but it probably does. + +@item +Change the definition of the @samp{STACK_BOUNDARY} macro in +@file{gcc/config/i386/i386.h} from @samp{32} to +@samp{(TARGET_ALIGN_DOUBLE ? 64 : 32)}, and rebuild +@code{g77}. +@xref{Installation,,Installing GNU Fortran}, for more information. + +@item +Ensure that @file{crt0.o} or @file{crt1.o} +on your system guarantees a 64-bit +aligned stack for @code{main()}. +Some experimentation might be needed to determine this, and +access to source code to fix this. +While arranging this may typically +get more data properly aligned, it won't, by itself, +ensure they all are. + +One approach to testing this is to write a @code{main()} program +in C or assembler that outputs the address of the stack pointer +(and/or frame pointer), and visually inspect the output to see +if the stack is 64-bit aligned. +If it is, try renaming the executable to longer and shorter names +and running the program again. +If the name of the executable is placed on the stack by @file{crt0.o} +or @file{crt1.o}, +the location of the stack should move, and this might help determine +whether it is kept on a 64-bit boundary. +@end itemize + +Yes, this is all more complicated than it should be. +The problems are best solved in @code{gcc} and the +libraries for the operating systems on such systems, +which need to be continuously updated to provide the +best alignment for newly released processors. +Managing this while remaining compatible with ABIs +on various systems can be challenging. + +@node Prefer Automatic Uninitialized Variables +@subsection Prefer Automatic Uninitialized Variables + +If you're using @samp{-fno-automatic} already, you probably +should change your code to allow compilation with @samp{-fautomatic} +(the default), to allow the program to run faster. + +Similarly, you should be able to use @samp{-fno-init-local-zero} +(the default) instead of @samp{-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, @samp{-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, @samp{-fno-init-local-zero} forces such +variables to be initialized to zero---when @code{SAVE}d (such as when +@samp{-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 @samp{-fno-automatic} and +@samp{-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 @code{f2c} compatibility +@cindex compatibility, @code{f2c} + +If you aren't linking with any code compiled using +@code{f2c}, try using the @samp{-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 @code{f2c}---it is compiled by a C +compiler, typically @code{gcc}.) + +@node Use Submodel Options +@subsection Use Submodel Options +@cindex Pentium optimizations +@cindex optimizations, Pentium +@cindex 586/686 CPUs +@cindex submodels + +Using an appropriate @samp{-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 and +Porting GNU CC}. + +For recent CPUs that don't have explicit support in +the released version of @code{gcc}, it may still be possible to get +improvements. +For instance, the flags recommended for 586/686 +(Pentium(Pro)) chips for building the Linux kernel are: + +@smallexample +-m486 -malign-loops=2 -malign-jumps=2 -malign-functions=2 +-fomit-frame-pointer +@end smallexample + +@noindent @samp{-fomit-frame-pointer} will, however, inhibit debugging +on x86 systems. + +@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. + +Information on bugs that show up when configuring, porting, building, +or installing @code{g77} is not provided here. +@xref{Problems Installing}. + +To find out about major bugs discovered in the current release and +possible workarounds for them, retrieve +@url{ftp://alpha.gnu.ai.mit.edu/g77.plan}. + +(Note that some of this portion of the manual is lifted +directly from the @code{gcc} manual, with minor modifications +to tailor it to users of @code{g77}. +Anytime a bug seems to have more to do with the @code{gcc} +portion of @code{g77}, +@xref{Trouble,,Known Causes of Trouble with GNU CC, +gcc,Using and Porting GNU CC}.) + +@menu +* But-bugs:: Bugs really in other programs or elsewhere. +* Actual Bugs:: Bugs and misfeatures we will fix later. +* 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 @code{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 @code{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 @code{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 @code{g77} maintainers have their hands full working on +just fixing and improving @code{g77}, without serving as a +clearinghouse for all bugs that happen to affect @code{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 @code{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 @url{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 ld error for user code +@cindex ld can't find strange names +On some systems, perhaps just those with out-of-date (shared?) +libraries, unresolved-reference errors happen when linking @code{g77}-compiled +programs (which should be done using @code{g77}). + +If this happens to you, try appending @samp{-lc} to the command you +use to link the program, e.g. @samp{g77 foo.f -lc}. +@code{g77} already specifies @samp{-lf2c -lm} when it calls the linker, +but it cannot also specify @samp{-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{-lf2c -lm} is insufficient to resolve code produced +by @code{g77}. + +@cindex undefined reference (_main) +@cindex linking error for user code +@cindex ld error for user code +@cindex code, user +@cindex ld can't find _main +If your program doesn't link due to unresolved references to names +like @samp{_main}, make sure you're using the @code{g77} command to do the +link, since this command ensures that the necessary libraries are +loaded by specifying @samp{-lf2c -lm} when it invokes the @code{gcc} +command to do the actual link. +(Use the @samp{-v} option to discover +more about what actually happens when you use the @code{g77} and @code{gcc} +commands.) + +Also, try specifying @samp{-lc} as the last item on the @code{g77} +command line, in case that helps. + +@node Large Common Blocks +@subsection Large Common Blocks +@cindex common blocks, large +@cindex large common blocks +@cindex linker errors +@cindex 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 @code{ld}, fixed in +more recent versions of @code{binutils}, such as version 2.6. + +@node Debugger Problems +@subsection Debugger Problems +@cindex @code{gdb} support +@cindex support, @code{gdb} +There are some known problems when using @code{gdb} on code +compiled by @code{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. + +@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 @code{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{gcc/f/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 +@code{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 @code{csh} and derivatives) or +@kbd{ulimit -s} (in @code{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 +@samp{-fno-automatic} option to reduce stack usage, probably at the +expense of speed. + +@xref{Maximum Stackable Size}, for information on patching +@code{g77} to use different criteria for placing local +non-automatic variables and arrays on the stack. + +@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 @samp{-fno-automatic}, +nor changing the cut-off point for @code{g77} for using the stack, +will solve the problem by changing the placement of these +large arrays, as they are @emph{necessarily} automatic. + +@code{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 @samp{test} +@cindex @samp{test} programs +@cindex programs named @samp{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 @samp{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 @code{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 +@code{man}, @code{info} (on GNU systems), @code{setenv} (or +@code{set} and @code{env}), @code{which}, and @code{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 +@code{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. + +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). + +Plans call for improving @code{g77} so that it can offer 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 an array, or checking for agreement between +calling and called procedures. + +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 spaces, 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 @code{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 @code{g77}, +use binary arithmetic to represent these approximations. + +Therefore, the exact value of any floating-point approximation +as manipulated by @code{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 denomenator 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 @code{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{libf2c} library, +used by @code{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 _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 @code{g77} and/or @code{libf2c} 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. + +@include bugs.texi + +@node Missing Features +@section Missing Features + +This section lists features we know are missing from @code{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:: +* 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:: +* 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:: +* Suppressing Space Padding:: +* Fortran Preprocessor:: +* Bit Operations on Floating-point Data:: + +New facilities: +* POSIX Standard:: +* Floating-point Exception Handling:: +* Nonportable Conversions:: +* Large Automatic Arrays:: +* Support for Threads:: +* Increasing Precision/Range:: + +Better diagnostics: +* 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:: +* Bounds Checking at Run Time:: + +Debugging: +* Labels Visible to Debugger:: +@end menu + +@node Better Source Model +@subsection Better Source Model + +@code{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, @code{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, @code{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 @code{-Wno-col73to80} option. + +@node Fortran 90 Support +@subsection Fortran 90 Support +@cindex Fortran 90 support +@cindex support, Fortran 90 + +@code{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 @code{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 @code{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 + +@code{g77} doesn't allow intrinsics in @code{PARAMETER} statements. +This feature is considered to be absolutely vital, even though it +is not standard-conforming, and is scheduled for version 0.6. + +Related to this, @code{g77} doesn't allow non-integral +exponentiation in @code{PARAMETER} statements, such as +@samp{PARAMETER (R=2**.25)}. +It is unlikely @code{g77} will ever support this feature, +as doing it properly requires complete emulation of +a target computer's floating-point facilities when +building @code{g77} as a cross-compiler. +But, if the @code{gcc} back end is enhanced to provide +such a facility, @code{g77} will likely use that facility +in implementing this feature soon afterwards. + +@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 + +@code{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 -i8 +@cindex f2c +@cindex increasing precision +@cindex precision, increasing +@cindex increasing range +@cindex range, increasing +@cindex Toolpack +@cindex Netlib + +Some compilers, such as @code{f2c}, have an option (@samp{-r8} 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 (@samp{-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.) + +@code{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 @code{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 INTEGER*2 support +@cindex LOGICAL*1 support + +@code{g77} doesn't fully support @code{INTEGER*2}, @code{LOGICAL*1}, +and similar. +Version 0.6 will provide full support for this very +popular set of features. +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 REAL*16 support +@code{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. +This is scheduled for version 0.6. + +@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 DIMENSION statement +@cindex statements, DIMENSION + +@code{g77} doesn't support more general expressions to dimension +arrays, such as array element references, function +references, etc. + +For example, @code{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 + +@code{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 @code{g77}. + +@node Sensible Non-standard Constructs +@subsection Sensible Non-standard Constructs + +@code{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 @code{g77} (though @samp{-fpedantic} should +trigger warnings about such non-standard constructs). + +Until @code{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, @code{g77} already has been changed to +allow this combination, because although the general +problem of gratuitously rejecting unambiguous and +``safe'' constructs still exists in @code{g77}, this +particular construct was deemed useful enough that +it was worth fixing @code{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 @code{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 @code{g77} just for cases like yours. + +@node FLUSH Statement +@subsection @code{FLUSH} Statement + +@code{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 + +@code{g77} doesn't support @samp{FORMAT(I<J>)} and the like. +Supporting this requires a significant redesign or replacement +of @code{libf2c}. + +However, a future version of @code{g77} might support +this construct when the expression is constant. For +example: + +@smallexample + PARAMETER (IWIDTH = 12) +10 FORMAT (I<IWIDTH>) +@end smallexample + +In the meantime, 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 + +@code{g77} needs to provide some way, a la @code{gcc}, for @code{g77} +code to specify explicit assembler code. + +@node Q Edit Descriptor +@subsection Q Edit Descriptor +@cindex FORMAT statement +@cindex Q edit descriptor + +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{libf2c}. + +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 + +@code{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 + +@code{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 + +@code{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 @code{g77}, partly +because it requires a great deal of work either upgrading or +replacing @code{libf2c}. + +@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 + +@code{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 @code{g77} itself, but +require much more work on @code{libf2c}. + +@node ENCODE and DECODE +@subsection @code{ENCODE} and @code{DECODE} +@cindex ENCODE statement +@cindex statements, ENCODE +@cindex DECODE statement +@cindex statements, DECODE + +@code{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 @code{g77}. + +@node Suppressing Space Padding +@subsection Suppressing Space Padding of Source Lines + +@code{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 +@code{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. +@code{g77} should return the favor by offering conformance +to Digital's approach to handling the above example. + +@node Fortran Preprocessor +@subsection Fortran Preprocessor + +@code{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 AND intrinsic +@cindex intrinsics, AND +@cindex OR intrinsic +@cindex intrinsics, OR +@cindex SHIFT intrinsic +@cindex intrinsics, SHIFT + +@code{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 @code{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 POSIX Standard +@subsection @code{POSIX} Standard + +@code{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 @code{gcc} backend and, consequently, @code{g77}, currently provides no +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 inherited from the system-dependent startup code. + +Most systems provide some C-callable mechanism to change this; this can +be invoked at startup using @code{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 an x86-based GNU system: + +@smallexample +#include <fpu_control.h> +void __attribute__ ((constructor)) +trapfpe () @{ + (void) __setfpucw (_FPU_DEFAULT & + ~(_FPU_MASK_IM | _FPU_MASK_ZM | _FPU_MASK_OM)); +@} +@end smallexample + +@node Nonportable Conversions +@subsection Nonportable Conversions +@cindex nonportable conversions +@cindex conversions, nonportable + +@code{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 @code{g77} +when the @samp{-fugly} 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, +@code{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 @code{g77} nor the @code{libf2c} library +are thread-safe, nor does @code{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 Gracefully Handle Sensible Bad Code +@subsection Gracefully Handle Sensible Bad Code + +@code{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 @samp{-ff2c-intrinsics-disable}, +@code{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 + +@samp{-Wconversion} and related should flag places where non-standard +conversions are found. +Perhaps much of this would be part of @samp{-Wugly*}. + +@node Non-standard Intrinsics +@subsection Non-standard Intrinsics + +@code{g77} needs a new option, like @samp{-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 + +@code{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 @code{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 + +@code{g77} needs to support @samp{-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 + +@code{g77} needs a @samp{-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 + +@code{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 + +@code{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, @code{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, @code{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 + +@code{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 + +@code{g77} needs a set of options such as @samp{-Wugly*}, @samp{-Wautomatic}, +@samp{-Wvxt}, @samp{-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 + +@code{g77} should warn about unused labels when @samp{-Wunused} is in effect. + +@node Informational Messages +@subsection Informational Messages + +@code{g77} needs an option to suppress information messages (notes). +@samp{-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 + +@code{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 Bounds Checking at Run Time +@subsection Bounds Checking at Run Time + +@code{g77} should offer run-time bounds-checking of array/subscript references +in a fashion similar to @code{f2c}. + +Note that @code{g77} already warns about references to out-of-bounds +elements of arrays when it detects these at compile time. + +@node Labels Visible to Debugger +@subsection Labels Visible to Debugger + +@code{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 underscores + +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 COMMON statement +@cindex statements, COMMON +@cindex naming conflicts + +@code{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 @code{g77} does not, +to be compatible with @code{f2c}. + +@code{g77} could special-case the way it handles +@code{BLOCK DATA}, since it is not compatible with @code{f2c} in this +particular area (necessarily, since @code{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 @code{g77} would treat these references as requests to +force-load BLOCK DATA program units. + +In that case, if @code{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, +@code{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*(*) + +@code{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 f77 support +@cindex support, f77 + +In the opinion of many experienced Fortran users, +@samp{-fno-backslash} should be the default, not @samp{-fbackslash}, +as currently set by @code{g77}. + +First of all, you can always specify +@samp{-fno-backslash} to turn off this processing. + +Despite not being within the spirit (though apparently within the +letter) of the ANSI FORTRAN 77 standard, @code{g77} defaults to +@samp{-fbackslash} because that is what most UNIX @code{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 @samp{-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 @samp{-fno-backslash} the default for GNU +Fortran and thus require users of UNIX @code{f77} and @code{f2c} +to specify @samp{-fbackslash} to get the UNIX behavior. + +However, the realization that @code{g77} is intended as +a replacement for @emph{UNIX} @code{f77}, caused the author +to choose to make @code{g77} as compatible with +@code{f77} as feasible, which meant making @samp{-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 @code{f77} to do, by default?'' +Although at least one UNIX @code{f77} does not provide +@samp{-fbackslash} as a default, it appears that +the majority of them do, which suggests that +the majority of code that is compiled by UNIX @code{f77} +compilers expects @samp{-fbackslash} to be the default. + +It is probably the case that more code exists +that would @emph{not} work with @samp{-fbackslash} +in force than code that requires it be in force. + +However, most of @emph{that} code is not being compiled +with @code{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 +@code{g77}'s default of @samp{-fbackslash} than would +exist for the majority of UNIX @code{f77} users who +would have to modify existing, working build procedures +to explicitly specify @samp{-fbackslash} if that was +not the default. + +One suggestion has been to configure the default for +@samp{-fbackslash} (and perhaps other options as well) +based on the configuration of @code{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 @code{gcc}. +To change them for @code{g77}, you must first change them +for @code{gcc}. +Do not ask the maintainers of @code{g77} to do this for you, +or to disassociate @code{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 + +@code{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, @code{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} @code{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 +@code{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 + +@code{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 @code{g77} as +an invalid reference to the @code{SQRT} intrinsic function, +because the reference is a subroutine invocation. + +First, @code{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, @code{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, @code{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, @code{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, @code{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, @code{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 + +@code{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 +@code{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 @code{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 @code{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. +@code{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 +@code{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 @samp{-fugly}, 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. +@code{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!) + +@node Order of Side Effects +@subsection Order of Side Effects +@cindex side effects, order of evaluation +@cindex order of evaluation, side effects + +@code{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 @code{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 +@samp{-W} options (for instance, @samp{-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 @code{g77} diagnostics. +Probably, as of version 0.6, @code{g77} will +no longer print the text of the source line, instead printing +the column number following the file name and line number in +a form that GNU Emacs recognizes. +This change is expected to speed up and reduce the memory usage +of the @code{g77} compiler. +@c +@c Say this when it is true -- hopefully 0.6, maybe 0.7 or later. --burley +@c +@c GNU Fortran always tries to compile your program if possible; it never +@c gratuitously rejects a program whose meaning is clear merely because +@c (for instance) it fails to conform to a standard. In some cases, +@c however, the Fortran standard specifies that certain extensions are +@c forbidden, and a diagnostic @emph{must} be issued by a conforming +@c compiler. The @samp{-pedantic} option tells GNU Fortran to issue warnings +@c in such cases; @samp{-pedantic-errors} says to make them errors instead. +@c This does not mean that @emph{all} non-ANSI constructs get warnings +@c or errors. + +@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 +How do system administrators and users manage multiple incompatible +Fortran compilers on their systems? +How can @code{g77} contribute to this, or at least avoiding +intefering with it? + +Currently, @code{g77} provides rudimentary ways to choose whether to +overwrite portions of other Fortran compilation systems +(such as the @code{f77} command and the @code{libf2c} library). +Is this sufficient? +What happens when users choose not to overwrite these---does +@code{g77} work properly in all such installations, picking +up its own versions, or does it pick up the existing ``alien'' +versions it didn't overwrite with its own, possibly leading +to subtle bugs? + +@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. +* Patches: Sending Patches. How to send a patch for GNU Fortran. +@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 + +@node Bug Lists +@section Where to Report Bugs +@cindex bug report mailing lists +@kindex fortran@@gnu.ai.mit.edu +Send bug reports for GNU Fortran to @email{fortran@@gnu.ai.mit.edu}. + +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 @code{tar} archive, and, whether you need to +do that, it is acceptable to then compress the single file (@code{tar} +archive or source file) +using @code{gzip} and encode it via @code{uuencode}. +Do not use any MIME stuff---the current maintainer can't decode this. +Using @code{compress} instead of @code{gzip} is acceptable, assuming +you have licensed the use of the patented algorithm in +@code{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 @code{g77} with the @samp{-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 +A complete input file that will reproduce the bug. +If the bug is in the compiler proper (@file{f771}) and +you are using the C preprocessor, run your +source file through the C preprocessor by doing @samp{g77 -E +@var{sourcefile} > @var{outfile}}, then include the contents of +@var{outfile} in the bug report. (When you do this, use the same +@samp{-I}, @samp{-D} or @samp{-U} options 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; and 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 +frequently depend on every little detail of the function they happen in. + +@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 @samp{-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 @code{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 @samp{-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 @code{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. + +@xref{Sending Patches}, 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 Sending Patches +@section Sending Patches for GNU Fortran + +If you would like to write bug fixes or improvements for the GNU Fortran +compiler, that is very helpful. +Send suggested fixes to the bug report +mailing list, @email{fortran@@gnu.ai.mit.edu}. + +Please follow these guidelines so we can study your patches efficiently. +If you don't follow these guidelines, your information might still be +useful, but using it will take extra work. Maintaining GNU Fortran is a lot +of work in the best of circumstances, and we can't keep up unless you do +your best to help. + +@itemize @bullet +@item +Send an explanation with your changes of what problem they fix or what +improvement they bring about. For a bug fix, just include a copy of the +bug report, and explain why the change fixes the bug. + +(Referring to a bug report is not as good as including it, because then +we will have to look it up, and we have probably already deleted it if +we've already fixed the bug.) + +@item +Always include a proper bug report for the problem you think you have +fixed. We need to convince ourselves that the change is right before +installing it. Even if it is right, we might have trouble judging it if +we don't have a way to reproduce the problem. + +@item +Include all the comments that are appropriate to help people reading the +source in the future understand why this change was needed. + +@item +Don't mix together changes made for different reasons. +Send them @emph{individually}. + +If you make two changes for separate reasons, then we might not want to +install them both. We might want to install just one. If you send them +all jumbled together in a single set of diffs, we have to do extra work +to disentangle them---to figure out which parts of the change serve +which purpose. If we don't have time for this, we might have to ignore +your changes entirely. + +If you send each change as soon as you have written it, with its own +explanation, then the two changes never get tangled up, and we can +consider each one properly without any extra work to disentangle them. + +Ideally, each change you send should be impossible to subdivide into +parts that we might want to consider separately, because each of its +parts gets its motivation from the other parts. + +@item +Send each change as soon as that change is finished. Sometimes people +think they are helping us by accumulating many changes to send them all +together. As explained above, this is absolutely the worst thing you +could do. + +Since you should send each change separately, you might as well send it +right away. That gives us the option of installing it immediately if it +is important. + +@item +Use @samp{diff -c} to make your diffs. Diffs without context are hard +for us to install reliably. More than that, they make it hard for us to +study the diffs to decide whether we want to install them. Unidiff +format is better than contextless diffs, but not as easy to read as +@samp{-c} format. + +If you have GNU @code{diff}, use @samp{diff -cp}, which shows the name of the +function that each change occurs in. +(The maintainer of GNU Fortran currently uses @samp{diff -rcp2N}.) + +@item +Write the change log entries for your changes. We get lots of changes, +and we don't have time to do all the change log writing ourselves. + +Read the @file{ChangeLog} file to see what sorts of information to put +in, and to learn the style that we use. The purpose of the change log +is to show people where to find what was changed. So you need to be +specific about what functions you changed; in large functions, it's +often helpful to indicate where within the function the change was. + +On the other hand, once you have shown people where to find the change, +you need not explain its purpose. Thus, if you add a new function, all +you need to say about it is that it is new. If you feel that the +purpose needs explaining, it probably does---but the explanation will be +much more useful if you put it in comments in the code. + +If you would like your name to appear in the header line for who made +the change, send us the header line. + +@item +When you write the fix, keep in mind that we can't install a change that +would break other systems. + +People often suggest fixing a problem by changing machine-independent +files such as @file{toplev.c} to do something special that a particular +system needs. Sometimes it is totally obvious that such changes would +break GNU Fortran for almost all users. We can't possibly make a change like +that. At best it might tell us how to write another patch that would +solve the problem acceptably. + +Sometimes people send fixes that @emph{might} be an improvement in +general---but it is hard to be sure of this. It's hard to install +such changes because we have to study them very carefully. Of course, +a good explanation of the reasoning by which you concluded the change +was correct can help convince us. + +The safest changes are changes to the configuration files for a +particular machine. These are safe because they can't create new bugs +on other machines. + +Please help us keep up with the workload by designing the patch in a +form that is good to install. +@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{fortran@@gnu.ai.mit.edu}. +@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 @code{g77}, first decide +what kind of option you wish to add. +Search the @code{g77} and @code{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 @code{g77} and @code{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{gcc/f/lang-options.h}, +which is used during the build of @code{gcc} to +build a list of all options that are accepted by +at least one language's compiler. +This list goes into the @samp{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 @samp{lang_option_decode}, which, for +@code{g77}, is in @file{gcc/f/com.c} and just +calls @samp{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 @samp{-fno-asm} option; +even though the @code{f771} version of @samp{lang_decode_option} +rejects @samp{-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 @samp{-fno-asm}---perhaps +a warning about this would be helpful if it were +possible. + +Code that processes Fortran options is found in +@file{gcc/f/top.c}, function @samp{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{gcc/f/top.c}. +Many of these defaults are actually macros defined +in @file{gcc/f/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 @code{g77}. + +Accessor macros for Fortran options, used by code +in the @code{g77} FFE, are defined in @file{gcc/f/top.h}. + +@emph{Compiler options} are listed in @file{gcc/toplev.c} +in the array @samp{f_options}. +An option not listed in @samp{lang_options} is +looked up in @samp{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 way @code{f771} handles the @samp{-fset-g77-defaults} +option, which is always provided as the first option when +called by @code{g77} or @code{gcc}. + +This code is in @samp{ffe_decode_options} in @file{gcc/f/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 @samp{-fset-g77-defaults} option is passed to @code{f771} +automatically because of the specification information +kept in @file{gcc/f/lang-specs.h}. +This file tells the @code{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{gcc/f/lang-specs.h} that @samp{-fset-g77-defaults}, +@samp{-fversion}, and other options are passed, as appropriate, +even when the user has not explicitly specified them. +Other ``internal'' options such as @samp{-quiet} also +are passed via this mechanism. + +@node Projects +@chapter Projects +@cindex projects + +If you want to contribute to @code{g77} by doing research, +design, specification, documentation, coding, or testing, +the following information should give you some ideas. + +@menu +* Efficiency:: Make @code{g77} itself compile code faster. +* Better Optimization:: Teach @code{g77} to generate faster code. +* Simplify Porting:: Make @code{g77} easier to configure, build, + and install. +* More Extensions:: Features many users won't know to ask for. +* Machine Model:: @code{g77} should better leverage @code{gcc}. +* Internals Documentation:: Make maintenance easier. +* Internals Improvements:: Make internals more robust. +* Better Diagnostics:: Make using @code{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 @samp{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 @code{g77}, don't pass line/column pairs where +a simple @samp{ffewhere} type, which points to the error as much as is +desired by the configuration, will do, and don't pass @samp{ffelexToken} types +where a simple @samp{ffewhere} type will do. +Then, allow new default +configuration of @samp{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 @code{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 @code{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{libf2c} and #include'ing the resulting +file in @code{f2c}+@code{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 @samp{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{libf2c} would be moved at least to the +@code{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 +@code{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 @code{g77} uses +@code{gcc} rather than @code{f2c} calling conventions.) + +@item +Do something useful with @samp{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 @code{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{libf2c}) should improve portability as well as +produce more optimal code. +Further, @code{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, @code{g77} should produce the equivalent +of a @code{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, @code{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 @code{g77}, and Fortran in +general, in the long run. +Some of these items really pertain to improving @code{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 +@cindex concatenation +@cindex CHARACTER*(*) +Support arbitrary operands for concatenation, even in contexts where +run-time allocation is required. + +@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{libf2c} 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 @code{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{libf2c} or its replacement. + +@item +F90 and @code{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 @code{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 @samp{REAL_VALUE_TYPE} to represent floating-point constants +exclusively so the target float format need not be required. +This +means changing the way @code{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 @code{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 @code{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 @code{g77} works and how to port it is needed. +Much of this should be done only after the redesign planned for +0.6 is complete. + +@node Internals Improvements +@section Internals Improvements + +Some more items that would make @code{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 @samp{-D} to establish requirements +to achieve desired implementation dialect via @file{proj.h}. + +@item +Clean up used tokens and @samp{ffewhere}s in @samp{ffeglobal_terminate_1}. + +@item +Replace @file{sta.c} @samp{outpooldisp} mechanism with @samp{malloc_pool_use}. + +@item +Check for @samp{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 @code{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 @samp{ffebld_new} calls (those outside of @file{ffeexpr.c} or +inside but invoked via paths not involving @samp{ffeexpr_lhs} or +@samp{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 @samp{ffebld_list_new} (or whatever) calls might not be matched by +@samp{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 +@samp{ffestorag} objects, so maybe the backend (and other parts of the front +end) can notice that and handle like an @samp{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), +@samp{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 +@end ifset + +@ifset USING +@node Diagnostics +@chapter Diagnostics +@cindex diagnostics + +Some diagnostics produced by @code{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 @code{info} +command that displays the explanation is given in 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 @code{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 @code{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. +@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 +@samp{REAL}) or @samp{DIMAG(@var{expr})} (if @var{intrinsic} +is @samp{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 @code{g77} option @samp{-ff90}, to enable the +Fortran 90 interpretation. + +@item +Compile with the @code{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 Contact via Internet email: burley@@gnu.ai.mit.edu +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 @code{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 @samp{-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 @samp{-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 @code{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 @code{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 @code{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 @code{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 @code{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 @samp{-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 @samp{-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 @code{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 @samp{-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. + +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. +Comment lines are indicated by the letter @samp{C} or the symbol +@samp{*} in column 1. +(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 @samp{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 @samp{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} or @samp{.for}, the file +will normally be compiled @emph{without} preprocessing by @code{g77}. + +Change the file's suffix from @samp{.f} to @samp{.F} (or, on +systems with case-insensitive file names, to @samp{.fpp}) or +from @samp{.for} to @samp{.fpp}. +@code{g77} compiles files with such names @emph{with} +preprocessing. + +Or, learn how to use @code{gcc}'s @samp{-x} option to specify +the language @samp{f77-cpp-input} for Fortran files that +require preprocessing. +@xref{Overall Options,,gcc,Using and Porting GNU CC}. + +@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). + +These disagreements, if not diagnosed, could result in a +compiler crash if the compiler attempted to inline a reference +to @var{name} within a calling program unit that disagreed +with the @var{name} program unit regarding whether the +procedure is a subroutine or function, the type of the +return value of the procedure (if it is a function), the +number of arguments the procedure accepts, or the type +of each argument. + +Such disagreements @emph{should} be fixed in the Fortran +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 by @code{g77} with the @samp{-fno-globals} option. + +The @samp{-fno-globals} option disables these diagnostics, and +also disables all inlining of references to global procedures +to avoid compiler crashes. +The diagnostics are actually produced, but as warnings, unless +the @samp{-Wno-globals} option also is specified. + +After using @samp{-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. + +@end ifset + +@node Index +@unnumbered Index + +@printindex cp +@summarycontents +@contents +@bye |